12.2. Coding conventions¶
12.2.1. Code style¶
Like most Python projects, we try to adhere to PEP-8 (Style Guide for Python Code) and PEP-257 (Docstring Conventions) with any modifications documented here. Be sure to read those documents if you intend to contribute code to Cate project.
12.2.2. Spaces or tabs, etc¶
- According to PEP-8, we use 4 spaces for indention.
- Lines shall be no longer than 120 characters.
- Put a 2-line space between global classes, functions, variable declarations. Put a 1-line space between class methods.
12.2.3. Private components and properties¶
- According to PEP-8, we use a leading underscore to denote components as private.
- In most cases, class instance variables should be private. Use the
@propertyannotation on a getter method to export them in a controlled way. Think twice if you want write access.
- Use triple quotes for docstrings
- Use single docstrings
"""bla bla bla."""if you have no docstring attributes and if the text fits into one line. Otherwise, add a line break after the opening
"""and before the closing
- Use the Sphinx-style docstring attributes, e.g.
:return:, etc and references, e.g.
- Use the Sphinx
#:syntax to document variables.
- All modules must have a docstring that explains a module’s intend, content, usage, and requirements that lead to its design.
- All public (API) classes must have a docstring that explains a class’
(single!) purpose and its constructor parameters passed to the
- All public (API) functions or methods must have a docstring that explains a function’s or method’s (single!) behaviour, parameter values + types and return value + type (if any).
- All public (API) variables must have a docstring that explains a variable’s purpose, value and type.
12.2.5. Type annotations¶
Use type annotations when it makes sense. It makes sense, when it helps
the IDE to point you to coding errors. It makes sense to help other
people understand our code. When it makes sense, use type types from the
new Python 3.5
typing module. However, if you allow a certain
function argument to be of multiple types, don’t try to construct wild
type annotation expressions, because this will reduce the readability of
the code again. In this case it is better to provide a reasonable
12.2.6. TODO comments¶
Feel free to use TODO comments in the code on your personal branches,
but avoid them on
master. If you need one, use following format
# TODO (forman, 20160613): bla bla bla
Ideally, TODO comments are backed by a GitHub issue providing more background info
# TODO (forman, 20160613): bla bla bla, see https://github.com/CCI-Tools/cate/issues/39