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.
All names should be as short as possible but as long as necessary to understand them.
The following table from RealPython.com summarizes the PEP8 naming conventions:
|Function||Use a lowercase word or words. Separate words by underscores to improve readability.||
|Variable||Use a lowercase single letter, word, or words. Separate words with underscores to improve readability.||
|Class||Start each word with a capital letter. Do not separate words with underscores. This style is called camel case.||
|Method||Use a lowercase word or words. Separate words with underscores to improve readability.||
|Constant||Use an uppercase single letter, word, or words. Separate words with underscores to improve readability.||
|Module||Use a short, lowercase word or words. Separate words with underscores to improve readability.||
|Package||Use a short, lowercase word or words. Do not separate words with underscores.||
Files, Folder, Dirs¶
|path||"D:\tmp\" or "D:\tmp\testfile_detections.csv"|
Files get an extension according to their content.
|.otdet||detections as bounding boxes|
|.ottrk||trajectories in pixel (and UTM) coordinates|
|.otrfpts||reference points to convert pixel to UTM coordinates|
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
If you are using VS Code, you may want to use the Python Docstring Generator extension.
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.
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):
|Paths||pathlib (distributed with Python since 3.4)|
|Neural networks||PyTorch, torchvision|
|Data handling||pandas, NumPy|
|Shape handling||GeoPandas, Shapely|
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] max-line-length = 88 docstring-convention=google