Python quick guidelines

The quality of the code can be assessed by how much time it takes to a new developer to understand what your code is doing.

Use a linter to help you practice these guidelines. I recommend flake8 that check the style and quality of your python code.

Quick guidelines

• keep your functions short (less than 30 lines)
• use docstring to document the modules, functions and classes
• respect naming conventions (use the right case at the right place)
• keep your lines short (less than 99 characters) by breaking them at the right place

Naming convention

It exists a few cases used throughout python:

• the snake_case more info: in lowercase with words separated by underscores.
• the PascalCase (or UpperCamelCase) more info: Start each word with a capital letter. Do not separate words with underscores.
• the UPPERCASE for constants: everything in caps with words separated by underscores.

Type	Naming Convention	Examples
Function	snake_case	function, my_function
Variable	snake_case	x, var, my_variable
Class	PascalCase	Model, MyClass
Method	snake_case	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	snake_case, keep short	module.py, my_module.py
Package	lowercase, keep short, avoid underscores	package, mypackage

Code layout

Blank lines

From https://peps.python.org/pep-0008/#blank-lines:

Surround top-level function and class definitions with two blank lines.

Method definitions inside a class are surrounded by a single blank line.

Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations).

Use blank lines in functions, sparingly, to indicate logical sections.

Examples

def foo(): # top-level function
    something = 5


def bar(): # top-level function
    somethingelse = 42

class A: # class
    CONSTANT = 2

    def foo(self): # method
        """bla.
        
        Returns
        -------
        int:
            the bla.
        """
        bla = self.CONSTANT

        return bla

    def bar(self, height: int = 10): # method
        """Compute the height.
        
        Parameters
        ----------
        height : int
            the new height.
        """
        bla = height


class B: # class
    pass

Line length

for code lines, PEP8 recommands not to exceed 99 characters and advice to stick to 79 characters. Do not make your variable name cryptic in order to meet this guideline.

comments and docstrings must be wrapped at 72 characters.

• blank lines between functions
• short lines
• short functions
• no comments inside functions
• typing hints (why using typing hints ?)
• use pathlib (why using pathlib ?)
• docstring with numpy conventions

Line breaking and indentation

Use 4 spaces indentation except for line continuation and in hanging indent.

Because it can be hard to keep a line under the limit of 99 characters, you can use line breaking. Python will assume line continuation when code is inside parenthesis.

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# Add an extra level of indentation to distinguish arguments from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

The closing brace/bracket/parenthesis on multiline constructs may be lined up under the first character of the line that starts the multiline construct.

my_list = [
    1, 2, 3,
    4, 5, 6,
]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
)

You can also break the line before using an operator.

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

Comments

Use inline comments sparingly. You must not state the obvious.

x = x + 1 # Increment x

Docstrings

Python has no convention for docstrings, but numpy docstring convention exists. See this summary of guidelines for more information.

Imports order

We can distinguish 3 types of python import:

• the standard library. It is including by default and does not need to be installed via pip. You can find pathlib, os, random, multiprocessing and many more.
• the external packages like numpy, pandas or matplotlib. They have to be installed via pip
• the internal packages or modules. They are references to your own code.

You should include them in the presented order i.e., the modules from the standard library, the external packages, the internal packages.