The Code Style Guide

For end-users, the most important parts of the software are functionality and UI/UX. But for developers, there is one more important aspect - code style. While ugly code can do everything that it has to do, developing it further may be a difficult task, especially if the developer didn't write the original code. Which one of the following do you prefer to read and work with? 

MyPath = '/file.txt'
from pathlib import *
import os.path,sys
def check(p):
  """Uses os.path.exist         """
  return os.path.exists(p)

def getF(
  p):
  """Not sure what this do, this just worked.
  """
  return Path(p
  )
result=[check(MyPath),getF(MyPath)]

or

import os.path
from pathlib import Path

FILE_PATH = '/file.txt'


def check_file_exists(path: str) -> bool:
    """Checks does file exists in path. Uses os.path.exists."""
    return os.path.exists(path)


def get_path_object(path: str) -> Path:
    """
    Returns Path object of the path provided in arguments.

    This is here for backward compatibility, will be removed in the future.
    """
    return Path(path)

result = [
    check_file_exists(FILE_PATH),
    get_path_object(FILE_PATH),
]

The second is definitely easier to read and understand. These scripts are small and even with the first code snippet you can understand what the code does pretty quickly, but what if the project has thousands and thousands of files in a really complex folder structure? Do you want to work with code that looks like the first example? You can save hours sometimes if you write beautiful code that follows the style guidelines.

The most important code style document for Python is PEP 8. This Python Enhancement Proposal lays out the majority of all Python code style guidelines. This article will cover the most important aspects of PEP 8.

Linters

But everyone makes mistakes and there are so many style rules that can be really difficult to remember and always follow. Luckily, we have amazing tools that help us - linters. While there are many linters, we'd like code jam participants to use flake8. Flake8 points out to you rules what you did break in your code so you can fix them.

Guidelines

Basics

For indentation, you should use 4 spaces. Using tabs is not suggested, but if you do, you can't mix spaces and tabs.

PEP 8 defines a maximum line length of 79 characters, however, we are not so strict - teams are welcome to choose a maximum line length between 79 and 119 characters.

2 blank lines should be left before functions and classes. Single blank lines are used to split sections and make logical breaks.

Naming

Module, file, function, and variable names (except type variables) should be lowercase and use underscores.

# File: my_module.py/mymodule.py

def my_function():
    my_variable = "value"

Class and type variable names should use the PascalCase style.

from typing import List


class MyClass:
    pass

ListOfMyClass = List[MyClass]

Constant names should use the SCREAMING_SNAKE_CASE style.

MY_CONSTANT = 1

You should avoid single-character names, as these might be confusing. But if you still do, you should avoid characters that may look like zero or one in some fonts: "O" (uppercase o), "l" (lowercase L), and "I" (uppercase i).

Operators

If you have a chain of mathematic operations that you split into multiple lines, you should put the operator at the beginning of the line and not the end of the line. 

# No
result = (
    1 +
    2 *
    3
)

# Yes
result = (
    1
    + 2
    * 3
)

If you ever check if something is equivalent to None, you should use is and is not instead of the == operator.

# No
if variable == None:
    print("Variable is None")

# Yes
if variable is None:
    print("Variable is None")

You should prefer using <item one> is not <item two> over not <item one> is <item two>. Using the latter makes it harder to understand what the expression is trying to do. 

# No
if not variable is None:
    print("Variable is not None")

# Yes - it is much easier to read and understand this than previous
if variable is not None:
    print("Variable is not None")

Imports

Imports should be at top of the file, the only things that should be before them are module comments and docstrings.

You shouldn't import multiple modules in one line, but give each module import its own line instead.

# No
import pathlib, os

# Yes
import os
import pathlib

Wildcard imports should be avoided in most cases. It clutters the namespace and makes it less clear where functions or classes are coming from.

# No
from pathlib import *

# Yes
from pathlib import Path

You should use isort imports order specification, which means:

  • Group by type: order of import types should be: __future__ imports, standard library imports, third-party library imports, and finally project imports.
  • Group by import method: inside each group, first should come imports in format import <package> and after them from <package> import <items>.
  • Order imports alphabetically: inside each import method group, imports should be ordered by package names.
  • Order individual import items by type and alphabetically: in from <package> import <items> format, <items> should be ordered alphabetically, starting with bare module imports.

Comments

Comments are really important because they help everyone understand what code does. In general, comments should explain why you are doing something if it's not obvious. You should aim to write code that makes it obvious what it is doing and you can use the comments to explain why and provide some context.

Keep in mind that just as important as having comments, is making sure they stay up to date. Out-of-date and incorrect comments confuse readers of your code (including future you).

Comments content should start with a capital letter and be a full sentence(s).

There are three types of comments: block comments, inline comments, and docstrings.

  • Block comments

    Probably most common comment type. Should be indented to the same level as the code they describe. Each line in the block comment has to start with # and should be followed by a single space. To separate paragraphs, use one line containing only #. 

    if variable is None or variable == 1:
    # If variable is None, something went wrong previously.
    #
    # Here starts a new important paragraph.

  • Inline comments

    You should prefer block comments over inline comments and use inline comments only where it is really necessary. Never use inline comments to explain obvious things like what a line does.

    If you want to use an inline comment on a variable, think first, maybe you can use a better variable name instead.

    After code and before the start of inline comments should be at least two spaces. Just like block comments, inline comments also have to start with # followed by a single space. 

    # Do not use inline comments to explain things
# that the reader can understand even without the inline comment.
my_variable = "Value!"  # Assign value to my_variable

# Here better variable name can be used like shown in the second line.
x = "Walmart"  # Shop name
shop_name = "Walmart"

# Sometimes, if something is not obvious, then inline comments are useful.
# Example is from PEP 8.
x = x + 1  # Compensate for border

  • Docstrings

    Last, but not least important comment type is docstring, which is a short version of documentation string. Docstring rules haven't been defined by PEP 8, but by PEP 257 instead.

    Docstrings should start and end with three quotes (""").

    There are two types of docstrings: one-line docstrings and multiline docstrings.

    One-line docstrings have to start and end in the same line, while multiline docstrings start and end in different lines. Multiline docstring has two parts: summary line and a longer description, which are separated by one empty line. The multiline docstring start and end quotes should be on different lines than the content. 

    # This is a one-line docstring.
"""This is one line module docstring."""


# This is a multiline docstring.
def my_function():
    """
    This is the summary line.

    This is the description.
    """

Too much for you?

Do all these style rules make your head explode? We have something for you! We have a song! We have The PEP 8 Song (featuring lemonsaurus)! Great way to get started with writing beautiful code.

Useful information for code jam participants