Coding Conventions

Preface

The aim of these coding standards is to help create a codebase with a 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 the 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 with overtime to conform to these conventions.

There are also pre-commit CI checks for python code style which will automatically fix the PR.

Python

Rules

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

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 recommended by black which 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 space 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 docstring documentation can be found here

C++

The customized Clang Format style is used for C++ code formatting. The style is defined in .clang-format file in the root of the repository. The style is based on the Google C++ style with some modifications.

Run scripts to check the code

It’s a good idea to install pre-commit on your repository:

$ pip install pre-commit
$ pre-commit install

The scripts will be run automatically before each commit and will fix the code style issues automatically.