CKAN Coding Guide

Please see https://docs.google.com/document/d/1QODm7cZtchBGtPbvYQV7qSGeVpI4PbgM8iYjthbWqUY/edit?usp=sharing

Approved

Proposed

• Testing
  • we could test:
    • simple unit tests
    • tests for helper functions
    • tests for modified actions
    • tests for verifying the output (html/api) by using the webtest library that is included in CKAN
  • have specific test.ini file in extension (which can refer the test-core.ini file and just overwrite some properties) and run the extension's tests separately with this config file
  • test method names should be clear and detailed (even if they are long)
  • starting with ckan 2.2 there's a new way of testing ckan in ckan/new_tests, explained here: http://docs.ckan.org/en/latest/contributing/testing.html. We don't have that version yet, but we could at least try to follow the same organization of tests:
    • controllers
    • lib: ( test for helpers)
    • logic: actions,auth, converters, validators
    • model
  • don't run core ckan tests with special test.ini
• Python Coding Standards ( mostly taken from http://docs.ckan.org/en/latest/contributing/python.html )
  • Do we use pep8 ?
  • Imports
    • Don’t use from module import * or from module import name. Instead just import module (as x) and then access names with module.name.
    • Make all imports at the start of the file, after the module docstring
  • String formatting: _(' ... {foo} ... {bar} ...').format(foo='foo-value', bar='bar-value')
  • Docstrings all modules, public functions and classes
    Use :param and :type to describe each parameter Use :returns and :rtype to describe each return Use :raises to describe each exception raised

Other Links

Interesting blog entry from the ckan team: http://ckan.org/2014/05/22/introducing-the-technical-team-and-contributing-to-the-ckan-code/