Coding Standards

= OKFN Coding Standards =

= Testing =

Pretty much all code should be under test. We use:


 * python: nosetests + assert (no need for unittest unless you really want it)
 * javascript: QUnit or JSTestdriver

= Python =

In general follow the python style guide (PSG) as formulated in PEP 8: http://www.python.org/dev/peps/pep-0008/

Formatting

 * Tabs vs. Spaces
 * Spaces
 * 4 spaces for a tab
 * 79 character limit: in general all lines should be wrapped at 79 characters
 * Quote character: use ' not " wherever possible (including docstrings)

Coding
As in PSG, e.g.:


 * all variables and method names are lower_case_with_underscores
 * class names: capital camel case
 * do not make extra functions or methods to wrap one line statements or calls to well known libraries unless there is a very good reason
 * if a method does not use the 'self' or 'cls' parameter, think: should it really be a method? most likely it should be a utility function as it has nothing to do with the class in question.
 * the @classmethod decorator should be used sparingly, consider is it really necessary? could its job be accomplished with a simple function or a factory class?
 * the first argument to a classmethod should be 'cls' not 'self'. 'self' is for instances.
 * for paste or pylons derived applications, use 'paste.deploy.converters.asbool' to check boolean configuration variables. do not try to rewrite this function or "set config variable to any value (e.g. false) to enable".

Documentation

 * Use sphinx style documentation conventions
 * See for function/method parameters: http://packages.python.org/an_example_pypi_project/sphinx.html#function-definitions
 * All arguments and return values of public apis *should* be documented

Checking
Use pylint: http://www.logilab.org/857

External Resources

 * 1) David Jeske post - very good.
 * 2) epytext

= CSS =


 * Indent: 2-space spaces
 * open bracket on same line as css-selector
 * space after selector before bracket

body { font-family: Arial; }

body, h1, h2 { } // or body, h1 h2 { display: block; }

= Javascript =

We follow these existing recommendations:


 * http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
 * http://javascript.crockford.com/code.html

Specific items:


 * Indentation: 4-spaces (not tabs)
 * See e.g. http://nodeguide.com/style.html#tabs-vs-spaces
 * Line-length: 80 characters
 * [Not yet consensus on] leading-commas - https://gist.github.com/357981

Testing:


 * Use QUnit or Jasmine

Documentation:


 * JSDoc: http://jsdoc.sourceforge.net/#usage
 * JS Doc Toolkit: http://code.google.com/p/jsdoc-toolkit/wiki/TagReference

= Distributed Version Control =

We use mercurial for most projects.

Branch-per-feature (and per-bug)
This approach is frequently recommended and may be adopted on a per-project basis:


 * Create a branch for each feature of bug. Naming convention: bug-{bug-name}, feature-{feature-name}
 * Close and merge into default once QA is done

For more discussion of how this works:


 * http://forceten.tidalwave.it/development/mercurial-best-practices/
 * http://www.rabbitmq.com/mercurial.html#branchperbug

= Web Applications =

URL Structure

 * In general do not use trailing slash on urls (but ensure you redirect 301 from trailing slash to non-trailing slash)
 * e.g.: /work not /work/, /work/9 not /work/9/

= RESTFul Services =


 * Singular is preferred to plural for entity names
 * No clear decision on this AFAICT
 * http://microformats.org/wiki/rest/urls - prefers plurals
 * http://blog.roberthahn.ca/articles/2007/04/06/url-design/ - prefers singulars
 * Searching/filtering should generally be done outside of REST
 * If done via REST must be done via url fragments and not via query parameters: e.g. /api/rest/person/age/39 (not /api/rest/person?age=39)