Python Style Guide

Having a consistent code style for a project is important as it allows developers to code correctly without thinking too much about it. It makes code easier to read, maintain and after becomming used to the style also easier to write.

Most of the time, it is not too important which standards to follow, but to decide in the team which ones you want to have and follow those consistently. To cite from PEP8:

A style guide is about consistency. Consistency with [PEP8] is important. Consistency within a project is more important. Consistency within one module or function is the most important.

Python has standards for general coding as well as for docstrings.

General Coding

PEP8

The PEP8 was posted in July 2001 and got an update in 2013.

PyFlakes

PyFlakes is a very common tool to check Python code for potential errors. I've added the codes to the long table below.

Docstrings

Python packages are usually documented on a function / class / method / package level directly in the code. The stuff in docs/ is often only for building HTML out of the Python code, organzinging things (e.g. which package to show first) and a user manual.

There is PEP257 which defines some basic stuff. Building on this, there are two docstring style guides which cannot be combined: NumpyDoc an Google.

Tools like napoleon in combination with Sphinx can automatically create nice docs of both of them.

NumpyDoc

See GitHub for the guide.

It looks as follows:

def get_meta(filepath, a_number, a_dict):
    """
    Get meta-information of an image.

    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo
    ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis
    parturient montes, nascetur ridiculus mus.

    Parameters
    ----------
    filepath : str
        Get metadata from this file
    a_number : int
        Some more details
    a_dict : dict
        Configuration

    Returns
    -------
    meta : dict
        Extracted meta information

    Raises
    ------
    IOError
        File could not be read
    """

Google Style Docstrings

See Github for the documentation.

It looks as follows:

def get_meta(filepath, a_number, a_dict):
    """Get meta-information of an image.

    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo
    ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis
    parturient montes, nascetur ridiculus mus.

    Args:
        filepath: Get metadata from this file.
        a_number: Some more details.
        a_dict: Configuration.

    Returns:
        Extracted meta information:

    Raises:
        IOError: File could not be read.
    """

SphinxDocString

It's super ugly and I find it hard to read, but this docstring type is also out there. SphinxDocString. They use reStructuredText:

def get_meta(filepath, a_number, a_dict):
    """
    Get meta-information of an image.

    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo
    ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis
    parturient montes, nascetur ridiculus mus.

    :param filepath: Get metadata from this file
    :type filepath: str
    :param a_number: Some more details
    :type a_number: int
    :param a_dict: Configuration
    :type a_dict: dict

    :returns: dict -- Extracted meta information

    :raises: IOError
    """

McCabe code complexity

The McCabe complexity measures how difficult it is to read your code. To quote from Wikipedia:

It is a quantitative measure of the number of linearly independent paths through a program's source code. [...] One of McCabe's original applications was to limit the complexity of routines during program development; he recommended that programmers should count the complexity of the modules they are developing, and split them into smaller modules whenever the cyclomatic complexity of the module exceeded 10.[2] This practice was adopted by the NIST Structured Testing methodology, with an observation that since McCabe's original publication, the figure of 10 had received substantial corroborating evidence, but that in some circumstances it may be appropriate to relax the restriction and permit modules with a complexity as high as 15.

I think McCabe complexity is one way to find spots where the could could be improved for readability, but I'm not certain how often that actually works.

There is a mccabe pytest plugin.

Linters

Linters are tools for static code analysis. Static code analysis is the task of analyzing a computer program without executing it. With executing the program, it would be dynamic code analysis which is done by coverage testing tools.

Common Python linters are:

• pycodestyle which replaces pep8
• pydocstyle
• flake8
• pyrama for checking package structure
• radon: Measuring the code complexity

What you should forget

• pylama: Only wraps some other tools. Use the pytest-plugins for those tools instead.

Error Codes

The following error codes are from pycodestyle and pydocstyle. I added to a couple why they exist and added a suggestion if I think you should take them (from ✓✓ for a strong YES to ✘✘ for a strong NO). Please also have a look at lintlyci.github.io/Flake8Rules which gives a lot of good examples for those rules.

There are also two footnotes for some codes:

(*) In the default configuration, the checks E121, E123, E126, E133, E226, E241, E242, E704, W503, W504 and W505 are ignored because they are not rules unanimously accepted, and PEP 8 does not enforce them. Please note that if the option –ignore=errors is used, the default configuration will be overridden and ignore only the check(s) you skip. The check W503 is mutually exclusive with check W504. The check E133 is mutually exclusive with check E123. Use switch --hang-closing to report E133 instead of E123. Use switch --max-doc-length=n to report W505.

(^) These checks can be disabled at the line level using the # noqa special comment. This possibility should be reserved for special cases.

Editor Support

You should let your editor do as many automatic formatting changes as you can.

• Sublime Text: Python Flake8 Lint (tested, works fine) and Auto PEP8 (not tested)
• Spyder: Auto PEP8 (not tested)

Notes on Details

Maximum Line Length

You might consider a maximum line lenght of 80 characters too extreme / outdated.

Well, please have a look how a 3-way merge would look like on your machine. This is how it looks like on mine:

And now look at files with 100 characters:

Sure, you can still do it. But for sure it also is less comfortable.

Let's see how famous projects do it (code on GitHub):

As you can see, all projects try to be below 79 characters per line. They only break it for tests and documentation. Not for code. While I admit there are some cases where you will get above the 79 character threshold, in most cases it just means that you should change the way you wrote your code. I've often seen it when you have many nested loops or conditions.

Another argument against longer line lengths is readability. Long lines are just harder to read. Newspapers could also have way longer lines and less columns. But they don't do that. Websites also make columns. Let's look at the number of characters in a line for a couple: