Coding Conventions

Preface

The aim of these coding standards is to help create a codebase with defined and consistent coding style that every contributor can get easily familiar with. This will in enhance code readability as there will be no different coding styles from different contributors and everything will be documented. Also PR diffs will be smaller because of unified coding style. Finally static typing will help in hunting down potential bugs before the code is even run.

Contributed code will not be refused merely because it does not strictly adhere to these conditions; as long as it’s internally consistent, clean, and correct, it probably will be accepted. But don’t be surprised if the “offending” code gets fiddled over time to conform to these conventions.

There are also github actions CI checks for python code style which will annotate the PR diff for you to see the areas where your code is lacking compared to the set standard.

Rules

The code must be compatible with the oldest supported version of python which is 3.6

The project follows the generic coding conventions as specified in the Style Guide for Python Code, Docstring Conventions and Typing Conventions PEPs, clarified and extended as follows:

  • Do not use “*” imports such as from module import *. Instead, list imports explicitly.

  • Use 4 spaces per indentation level. No tabs.

  • No one-liner compound statements (i.e., no if x: return: use two lines).

  • Maximum line length is 88 characters as recomended by black wich is less strict than Docstring Conventions suggests.

  • Use “StudlyCaps” for class names.

  • Use “lowercase” or “lowercase_with_underscores” for function, method, variable names and module names. For short names, joined lowercase may be used (e.g. “tagname”). Choose what is most readable.

  • No single-character variable names, except indices in loops that encompass a very small number of lines (for i in range(5): ...).

  • Avoid lambda expressions. Use named functions instead.

  • Avoid functional constructs (filter, map, etc.). Use list comprehensions instead.

  • Use "double quotes" for string literals, and """triple double quotes""" for docstring’s. Single quotes are OK for something like

    f"something {'this' if x else 'that'}"
    
  • Use f-strings s = f"{x:.2f}" instead of old style formating with "%f" % x. string format method "{x:.2f}".format() may be used sparsely where it is more convenient than f-strings.

Whitespace

Python is not C/C++ so whitespace should be used sparingly to maintain code readability

  • Read the Whitespace in Expressions and Statements section of PEP8.

  • Avoid trailing whitespaces.

  • Do not use excessive whitespace in your expressions and statements.

  • You should have blank spaces after commas, colons, and semi-colons if it isn’t trailing next to the end of a bracket, brace, or parentheses.

  • With any operators you should use a space in on both sides of the operator.

  • Colons for slicing are considered a binary operator, and should not have any spaces between them.

  • You should have parentheses with no space, directly next to the function when calling functions function().

  • When indexing or slicing the brackets should be directly next to the collection with no space collection["index"].

  • Whitespace used to line up variable values is not recommended.

  • Make sure you are consistent with the formats you choose when optional choices are available.

General advice

  • Get rid of as many break and continue statements as possible.

  • Write short functions. All functions should fit within a standard screen.

  • Use descriptive variable names.

Writing documentation in the code

Here is an example of how to write good docstrings:

The numpy doctring documentation can be found here

It is a good practice to run pydocstyle check on your code or use a text editor that does it automatically):

$ pydocstyle filename.py

Run pycodestyle on your code

It’s a good idea to run pycodestyle on your code (or use a text editor that does it automatically):

$ pycodestyle filename.py

Run mypy on your code

It’s a good idea to run mypy on your code (or use a text editor that does it automatically):

$ mypy filename.py

Run pydocstyle on your code

It’s a good idea to run pycodestyle on your code (or use a text editor that does it automatically):

$ pycodestyle filename.py --max-line-length=88

Run black on your code

Another method of enforcing PEP8 is using a tool such as black. These tools tend to be very effective at cleaning up code, but should be used carefully and code should be retested after cleaning it. Try:

$ black --help