Home

Awesome

Open Knowledge Foundation Coding Standards

This document outlines coding standards for use at Open Knowledge Foundation. It is a living document, and we encourage pull request and issues to improve on or contest ideas as expressed.

Related documents

TL;DR

Languages

Our work is done in Python and Javascript (Node.js). There can be good reasons for writing a particular library or app in another language, but if you think this is the case, please raise this issue directly before starting any work.

For example apps that implement the OKF preferences, see the following:

Style and linting

Python

  1. Follow the Python Style Guide (PSG) as formulated in PEP-8: http://www.python.org/dev/peps/pep-0008/
  2. Use pylint to lint code.

The critical points are:

And other preferences:

Python 2/3

As a rule, all Python code should be written to support Python 2 and Python 3. There are some circumstances where, for new apps, we may want to write specifically for the Python 3 interpreter in order to take advantage of great new language features like asyncio, but at this stage, this is likely an exception and not the rule. No code should be written to be compatible with Python 2 only.

The python porting guide has great, practical advice on writing code for Python 2 and 3. Some choose to use helper libraries like six. In any case, it is strongly recommend to follow the advice from the Python porting guide and add the following snippet to all Python modules to ensure API consistency for strings, division, imports, and the print function.

# -*- coding: utf-8 -*-
from __future__ import division
from __future__ import print_function
from __future__ import absolute_import
from __future__ import unicode_literals

Javascript

  1. Use eslint to lint code.
  2. Prefer to write all new code in ES6 and compile/transpile with Webpack or Browserify. This applies to frontend and backend code. In some cases, the cost of transpilation (inflated file size) is too great (for small utility libraries), so use judgement.

The critical points are:

And other preferences:

Testing

Python

  1. Use tox with py.test to test code.

Javascript

  1. Use mocha to test code.
  2. Use Zombie.js or jsdom for tests that require a DOM.

Documentation

Python

Docstrings

Use Sphinx-style or Google-style documentation conventions.

User documentation

Prefer to make really good README.md files, rather than implementing a full documentation framework.

Javascript

Docstrings

Use Google-style documentation conventions.

User documentation

Prefer to make really good README.md files, rather than implementing a full documentation framework.

Frameworks

We prefer the following frameworks and libraries. If you want to use an *alternative to one of these please flag this before starting any work.

Python

Javascript

Version control

We use Git for all projects.

Branch management

We generally follow Git Flow, with some modifications, and some flexibility per project. The following should hold true for pretty much all projects:

Continuous integration and deployment

All projects must be configured with a CI server. We use Travis CI by default. The CI server must run the test suite with linting.

App deployment

All apps must be deployed from the CI server.

Package publication

All packages must be published to npm and pypi from the CI server. The procedure is:

  1. Create your package and prepare it for publication.
  2. Register the package on the appropriate registry.
  3. Give the okfn user owner rights on the package.
  4. Create tags for package versions.
  5. Use the Travis integration to publish on tags.

Web apps

URLs

RESTful APIs

Browser support

We support modern browsers. Notably, IE 10 and above. Our browser support is in sync with the browser support of Google web properties, as declared here

Further reading