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.||
|path||"D:\tmp\" or "D:\tmp\testfile_detections.csv"|
Files get a suffix according to their content.
|_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|
Each module, function, class or method should be described in a docstring (Google style)
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() """
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.
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
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.