Code Style Guidelines

Black

We use the black coding style, a flavour of PEP-8 for Python.

We use a pre-commit-hook to apply this style before committing, so you don’t have to bother about formatting. Just code how you feel comfortable and let the tool do the work for you (see Pre-commit Hooks).

If you want to apply the formatting without committing, use our developer tool tools/black.sh:

./tools/black.sh

DjLint

We use djlint to format our Django HTML templates.

We use a pre-commit-hook to apply this style before committing, so you don’t have to bother about formatting. Just code how you feel comfortable and let the tool do the work for you (see Pre-commit Hooks).

If you want to apply the formatting without committing, use our developer tool tools/djlint.sh:

./tools/djlint.sh

Prettier

We use prettier to format our static JS and CSS files.

We use a pre-commit-hook to apply this style before committing, so you don’t have to bother about formatting. Just code how you feel comfortable and let the tool do the work for you (see Pre-commit Hooks).

If you want to apply the formatting without committing, use our developer tool tools/prettier.sh:

./tools/prettier.sh

Linting

In addition to black, we use pylint to check the code for semantic correctness. Run pylint with our developer tool tools/pylint.sh:

./tools/pylint.sh

When you think a warning is a false positive, add a comment before the specific line:

# pylint: disable=unused-argument
def some_function(*args, **kwargs)

Note

Please use the string identifiers (unused-argument) instead of the alphanumeric code (W0613) when disabling warnings.

Hint

If you want to run both tools at once, use our developer tool tools/code_style.sh:

./tools/code_style.sh

Docstrings

Please add docstrings in the sphinx format (see Writing docstrings):

"""
[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
...

:return: [ReturnDescription]

:raises [ErrorType]: [ErrorDescription]
...
"""

Hint

In the model documentation, the parameters are not required, because they are automatically derived from the model field type.

Whenever you want to document module/class attributes which are not parameters (i.e. because they are not passed to the __init__()-function or contain static values), use inline comments:

#: Description of attribute
attribute = "value of this attribute"

See the configuration files settings and conf or constants for examples.

Shellcheck

All developer tools in the tools directory have to comply to the standards of shellcheck (see ShellCheck wiki). Shellcheck is run both in the CI-pipeline of CircleCI (see shellcheck/check) and as pre-commit hook (see Pre-commit Hooks) and can be run locally with:

shellcheck -x tools/*

False positives can be ignored with the syntax:

# shellcheck disable=SC2059