Coding Style

Most important

• all names and comments in english
• 4 spaces for indentation
• easily readable and testable code
• keep comments up-to-date
• all modules, classes, functions and methods have a docstring in google style
• typing for functions
• PEP8 as base for this python coding style

Python Code Layout

We are using PEP8 as a base for this python coding style.

Line Length

• maximum of 79 characters
• e.g. set the ruler in VSCode

Indentation

• 4 spaces for indentation
• alignment of arguments for line breaks in the argument list

def func(param1: int, param2: int,
         param3: float, param4: str,
         param5: str) -> str:
    # Code for function with 4 spaces as indent

Imports

• always at the beginning after comments about the module
• new line for each import
• grouped in the following order:
  1. standard library imports
  2. related third party imports
  3. local application/library specific imports

import os
import sys

import numpy as np

from myclass import MyClass  # Own class

Line breaks

• blank lines to structure the code in logic sections
• avoid to many blank lines
• line break before binary operators for long expressions

income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

White spacing

• avoid unnecessary white spaces
• no spaces before commas, semicolons, colons, opening brackets for argument lists, slicing parameters
• space around assignments (=, +=, ...), comparisons(==, !=, ...), booleans (and, or, not)
• if operators with different priorities, only add white space around the operators with the lowest priority
• but no spaces around argument assignments in functions

A = [[1, 2, 3],
     [4, 5, 6]]  # Align the lines after line break

A[:, 0] = A[:, 1]  

func(matrix=A, axis=0)  # No spaces for argument assignments

x = 3
z = 2*x - x**2  # Only spaces around the operator with lowest priority

Comments

• always up-to-date
• each function gets docstring (see below)
• block-comments: aligned with code, each line starts with '#' (also blank lines)
• inline-comments: at least 2 spaces apart from code, starting with '#' and a space

# Block-comment starts here.
# 
# Use blank lines for logic separation.
# Also blank lines get the '#' at the start.
# Block-comment ends here.

print('Hello world.')  # Inline-comment if needed

Variable Names

• classes: nouns (capital initial, CamelCase)
• functions: verbs (small letters, snake_case)
• variables: as needed (small letters, snake_case)
• constants: as needed (all capital letters, underscores if needed)
• never use l (small L), O (capital o), I (capital i) as a single character name

Example for names:

class Example:
    """Docstring in google style ..."""

def get_sum(param1: int, param2: int) -> int:
    """Docstring in google style ..."""
    return param1 + param 2

count_max = 19

Docstrings

We are using docstring with google style, please see this page for explicit information. and more examples
For functions and class methods a docstring could look like this:

def func(param1: str, param2: int) -> bool: 
    """Example function with types documented in the docstring. 
    Don`t forget the typing of the argument and return types.

    Args:
        param1 (str): The first parameter.
        param2 (int): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.
    """
    return True if string(param1) + param2 > 0 else False

1. first sentence to describe the function
2. list of arguments with name, type and description
3. list of returns with name, tape and description

Do not include the self parameter (for class methods) in the Args section.

Typing

• indicate the types of the arguments and returns for each function
• if more than one type possible: separate types with ' | ' (only available for Version 3.10)
• if no return: set return type to None: -> None

Example for function with several possible types and no return value:

def print_sum(param1: int | float, param2: int | float) -> None:
    """Docstring in google style ..."""
    print(param1 + param2)

Please see this page for more information on typing and type hints.

Keep in Mind

• no redundance
• no surprises in the code
• one class has only one purpose
• classes can be expanded, but not modified excessively
• derived class extends base class without restrictions or changes, derived classes can be used instead of basis class