Conventions¶
Line length¶
All Python code in this package should be PEP8 valid. However, we don’t enforce the 80-char line length rule. It is encouraged to have your code formatted in 80-char lines, but somewhere it’s just more readable to break this rule for a few characters. Long and descriptive test method names are a good example of this.
Note
Configuring your editor to display a line at 80th column helps a lot here and saves time.
Note
The line length rules also applies to non-python source files, such as documentation .rst files.
About imports¶
- Don’t use * to import everything from a module.
- Don’t use commas to import multiple stuff on a single line.
- Don’t use relative paths.
from collective.table.local import add_row
from collective.table.local import delete_rows
from collective.table.local import update_cell
instead of
from collective.table.local import *
from collective.table.local import add_row, delete_rows
from .local import update_cell
Sort imports¶
As another imports stylistic guide: Imports of code from other modules should always be alphabetically sorted with no empty lines between imports. The only exception to this rule is to keep one empty line between a group of from x import y and a group of import y imports.
from collective.table.tests.base import TableIntegrationTestCase
from plone.app.testing import login
import os
instead of
import os
from plone.app.testing import login
from collective.table.tests.base import TableIntegrationTestCase
Commit checklist¶
Before every commit you should:
- Run Unit tests.
- Run Syntax validation.
- Add an entry to Changelog (if applicable).
- Add/modify Sphinx documentation (if applicable).
Unit tests¶
Un-tested code is broken code.
For every feature you add to the codebase you must also add tests for it. Also write a test for every bug you fix to ensure it doesn’t crop up again in the future.
You run tests like this:
$ bin/test
Syntax validation¶
All Python source code should be PEP-8 valid and checked for syntax errors. Tool for checking this is vvv.
To validate your source code, run the following two commands:
$ bin/vvv src/spinnerchief
Note
It pays off to invest a little time to make your editor run pep8 and pyflakes on a file every time you save that file. Saves lots of time in the long run.
Changelog¶
Feature-level changes to code are tracked inside docs/HISTORY.txt. Examples:
- added feature X
- removed Y
- fixed bug Z
Add an entry every time you add/remove a feature, fix a bug, etc.
Sphinx documentation¶
Un-documented code is broken code.
For every feature you add to the codebase you should also add documentation for it to docs/.
After adding/modifying documentation, re-build Sphinx and check how it is displayed:
$ bin/sphinxbuilder
$ open docs/html/index.html
Documentation is automatically generated from these source files every time you push your code to GitHub. The post-commit hook is handled by ReadTheDocs and the results are visible at http://readthedocs.org/docs/spinnerchief.