Skip to content

Style Guide

toonarmycaptain edited this page Mar 19, 2019 · 5 revisions

Codestyle

Conform to PEP8 as much as possible/sensible.

As far as possible, keep to the 72, 79 character PEP8 guideline for docstrings and code respectively.

Breaking docstrings/code across lines where it hurts readability is not advised, although a hard limit of 100 characters is expected.
For example if stdout print(f"The minimum and maximum are: {minimum} and {maximum})" could be a compliant one-liner by reducing variable names to mini and maxi (to avoid the clearer shortening of min and max that would overwrite Python's built-in functions), then leave the line the way it is.

Inline comments on their own line should respect the limit, but comments inline following code may extend out to 120 characters, if necessary. Consideration should be given whether clarity would be retained by placing the comment on it's own line.

Clear, well documented code is the goal.

Docstrings

Broadly speaking, docstrings should follow ReStructuredText (reST) format:

def func(arg1: int, arg2: str):
    """
    Summary line.

    Extended description of function.

    :param arg1: int, description of arg1.  # eg :param param-name: param-type, description
    :param arg2: str, description of arg2.
    :raises ValueError if arg1 is equal to arg2

    :return: None, description of return value
    """

Groups of parameters/raised errors/return can be separated by a blank line for clarity. The PEP8 72 character limit for docstrings should be respected.

Use type hints. This can be invaluable for avoiding/finding bugs!

Imports

Generally, follow PEP8. Group import x and from x import y styles together, generally adding newlines for visual clarity, and brackets where multiple imports from one module exceed allowed line length. This project follows the following style:

import stdlib module

from stdlib_module import function
from subsequent_stdlib_module import another_function

import third_party_module

from third_party_module import function

import local_application_module

from local_application_module import function
from long_local_application_module import (function_1
                                           function_2,
                                           function_3,
                                           function_4,
                                           function_5,
                                           )
Clone this wiki locally