“PEP 8: Style Guide for Python Code” and “PEP 257: Docstring Conventions” aren’t exactly long, but they’re also not easily skimmable.

As I’ve just started to learn python, I should make an effort to internalise these best-practice conventions. To help me do that, I’m going to summarise PEP 8 and 257 here, as a quick reference for myself and anyone else who might find it useful.

This is not quite an exhaustive summary: I have omitted the really obvious stuff, and in some cases I’ve picked one approach where PEP8 allows a few.

These standards can hopefully help in every coders’ ongoing mission to write readable and expressive code.

Indentation, line-length & code wrapping

  • Always use 4 spaces for indentation (don’t use tabs)
  • Write in ASCII in Python 2 and UTF-8 in Python 3
  • Max line-length: 72 characters (especially in comments)
  • Always indent wrapped code for readablility
# Good:
result = some_function_that_takes_arguments(
    'argument one,
    'argument two',
    'argument three'

# Bad:
result = some_function_that_takes_arguments(
'argument one,
'argument two', 'argument three')
result2 = some_function_that_takes_arguments('argument one', 'argument two', 'argument three')


  • Don’t use wildcards
  • Try to use absolute imports over relative ones
  • When using relative imports, be explicit (with .)
  • Don’t import multiple packages per line
# Good:
import os
import sys
from mypkg.sibling import example
from subprocess import Popen, PIPE # Acceptable
from .sibling import example # Acceptable

# Bad:
import os, sys # multiple packages
import sibling # local module without "."
from mypkg import * # wildcards

Whitespace and newlines

  • 2 blank lines before top-level function and class definitions
  • 1 blank line before class method definitions
  • Use blank lines in functions sparingly
  • Avoid extraneous whitespace
  • Don’t use whitespace to line up assignment operators (=, :)
  • Spaces around = for assignment
  • No spaces around = for default parameter values
  • Spaces around mathematical operators, but group them sensibly
  • Multiple statements on the same line are discouraged
# Good:
spam(ham[1], {eggs: 2})
if x == 4:
    print x, y
    x, y = y, x
dict['key'] = list[index]
y = 2
long_variable = 3
hypot2 = x*x + y*y
c = (a+b) * (a-b)
def complex(real, imag=0.0):
    return magic(r=real, i=imag)

# Bad
spam ( ham[ 1 ], { eggs: 2 } ) # spaces inside brackets
if x == 4 : print x , y ; x , y = y , x # inline statements, space before commas
dict ['key'] = list [index] # space before dictionary key
y             = 2 # Using spaces to line up assignment operators
long_variable = 3
hypot2 = x * x + y * y # Too much space around operators
c = (a + b) * (a - b) # Too much space around operators
def complex(real, imag = 0.0):
    return magic(r = real, i = imag) # Spaces in default values


  • Keep comments up to date - incorrect comments are worse than no comments
  • Write in whole sentences
  • Try to write in “Strunk & White” English
  • Use inline comments sparingly & avoid obvious comments
  • Each line of block comments should start with “# “
  • Paragraphs in block comments should be separated by a line with a single “#”
  • All public functions, classes and methods should have docstrings
  • Docstrings should start and end with """
  • Docstring one-liners can be all on the same line
  • In docstrings, list each argument on a separate line
  • Docstrings should have a blank line before the final """
def my_function():
    """ A one-line docstring """

def my_other_function(parameter=False):
    A multiline docstring.

    Keyword arguments:
    parameter -- an example parameter (default False)


Naming conventions

  • Class names in CapWords
  • Method, function and variables names in lowercase_with_underscores
  • Private methods and properties start with __double_underscore
  • “Protected” methods and properties start with _single_underscore
  • If you need to use a reserved word, add a _ to the end (e.g. class_)
  • Always use self for the first argument to instance methods
  • Always use cls for the first argument to class methods
  • Never declare functions using lambda (f = lambda x: 2*x)
class MyClass:
    """ A purely illustrative class """

    __property = None

    def __init__(self, property_value):
        self.__property = property_value

    def get_property(self):
        """ A simple getter for "property" """

        return self.__property

    def default(cls):
        instance = MyClass("default value")
        return instance