Coding guidelines

We follow PEP8 as our basic style guideline for all Python code. The following sections describe key aspects of how the code is structured.

Note

For other languages, we try to follow a similar style like in PEP8. Exception to this rule goes to languages where the general trend diverges too much from the basic guideline used here (e.g., Java), so adopting those conventions is allowed.

Cross-compatible code

Not all functions are available between versions, so it’s important to write code that will be compatible from Python 2.7 through the most recent version of Python 3.

Indentation

Use 4 spaces for identation. Don’t use tabs.

Names

  • Variables, functions, methods, packages, modules
    • lower_case_with_underscores
  • Classes and Exceptions
    • CapWords
  • Protected methods and internal functions
    • _single_leading_underscore(self, ...)
  • Private methods
    • __double_leading_underscore(self, ...)
  • Constants
    • ALL_CAPS_WITH_UNDERSCORES

DocStrings

We follow Numpy’s docstring style for documenting methods and classes. For core API functions and methods, please try to follow as close as possible the conventions used in the code. For methods defining datasets, a simple docstring is allowed.

Use one-line docstrings for obvious functions.

"""Return the pathname of ``foo``."""

Multiline docstrings should include

  • Summary line
  • Use case, if appropriate
  • Parameters
  • Return type and semantics, unless None is returned
  • Exceptions (if any is raised)
def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """