Skip to content

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
file type .csv
file D:\tmp\testfile_detections.csv
path "D:\tmp\" or "D:\tmp\testfile_detections.csv"

File extensions

Files get an extension according to their content.

Extension Description
.otdet detections as bounding boxes
.ottrk trajectories in pixel (and UTM) coordinates
.otrfpts reference points to convert pixel to UTM coordinates

Code documentation

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

Docstrings for 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()
"""

Docstrings for 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

Note

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.

Dependencies

We try to develop OpenTrafficCam using as few dependencies as possible. For basic functionality we prefer packages that come with the Python standard distribution (like pathlib or Tkinter). However, OpenTrafficCam would not be possible without code from third party libraries, especially when it comes to videos, images, data analysis, neural networks or web development. These are the libraries we intend to use for specific functionalities throughout the whole framework (we are grateful to the authors):

Functionality Library
Paths pathlib (distributed with Python since 3.4)
Videos, Images OpenCV
Neural networks PyTorch, torchvision
Data handling pandas, NumPy
Shape handling GeoPandas, Shapely
Plotting, graphing Plotly
User interface Tkinter
Web Dash (dashboards)

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