Coding (Python)

Coding standards are not about right and wrong or good and bad. They are about uniformity, so people can easily read and contribute to the code regardless who worked on the software before.

For now, nearly all code is Python so we just agreed on coding conventions for the Python programming language. We basically follow the PEP 8 Style Guide for Python Code. A good summary and some additions can be found in the Hitchhikers Guide or at RealPython.com. Below we defined what we consider the most important standards.

Naming Conventions

All names should be as short as possible but as long as necessary to understand them.

General

The following table from RealPython.com summarizes the PEP8 naming conventions:

Type	Naming Convention	Examples
Function	Use a lowercase word or words. Separate words by underscores to improve readability.	`function, my_function`
Variable	Use a lowercase single letter, word, or words. Separate words with underscores to improve readability.	`x, var, my_variable`
Class	Start each word with a capital letter. Do not separate words with underscores. This style is called camel case.	`Model, MyClass`
Method	Use a lowercase word or words. Separate words with underscores to improve readability.	`class_method, method`
Constant	Use an uppercase single letter, word, or words. Separate words with underscores to improve readability.	`CONSTANT, MY_CONSTANT, MY_LONG_CONSTANT`
Module	Use a short, lowercase word or words. Separate words with underscores to improve readability.	`module.py, my_module.py`
Package	Use a short, lowercase word or words. Do not separate words with underscores.	`package, mypackage`

Files, Folder, Dirs

Naming Convention	Examples
dir	D:\tmp\
filename	testfile
suffix	_detections
filetype	.csv
file	D:\tmp\testfile_detections.csv
path	"D:\tmp\" or "D:\tmp\testfile_detections.csv"

Suffix

Files get a suffix according to their content.

Suffix	Description
_detections	detections as bounding boxes
_tracks-px	trajectories in pixel coordinates
_tracks-corr	trajectories in pixel coordinates corrected for lens distortion
_tracks-utm	trajectories transformed to UTM coordinates
_refpts	reference points to convert pixel to UTM coordinates

Docstrings

Each module, function, class or method should be described in a docstring (Google style)

Modules

Each file should start with the license snippet followed by a docstring describing the contents and usage of the module:

"""A one line summary of the module or program, terminated by a period.

Leave one blank line.  The rest of this docstring should contain an
overall description of the module or program.  Optionally, it may also
contain a brief description of exported classes and functions and/or usage
examples.

  Typical usage example:

  foo = ClassFoo()
  bar = foo.FunctionBar()
"""

Functions

Each function must be described by a docstring:

def hello_world(message: str = "Hello World", author: str = "Santa Claus"):
    """Deliver a message from an author to the world.

    "author says message"

    Args:
        message (str, optional): Message to deliver. Defaults to "Hello World".
        author (str, optional): Author name. Defaults to "Santa Claus".

    Returns:
        str: the message said
    """
    msg = author + " says " + message
    print(msg)

    return msg

If you are using VS Code, you may want to use the Python Docstring Generator extension.

Comments

If it is necessary to explain your code in between, use single line or block comments for some (or all) code that follows:

# This is an example for a single line comment

# This is an 
# example for a
# block comment

Try to avoid inline comments.

Linting/Autoformatting

To match PEP8 specs and write pretty code we use flake8 to check against structural and style errors and black for autoformatting. Additionally the package flake8-docstrings can be used to lint the docstrings.

The following settings are set in the .flake8 file:

[flake8]
max-line-length = 88
docstring-convention=google

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.