Code style in Python

May 28, 2014

Note: this summary is a subset of rules found in PEP 8, originally written by Guido van Rossum, Barry Warsaw, and Nick Coghlan.

If you’re new to Python, you should take the time to review the recommendations put forth in the Style Guide for Python Code. Though it was written in 2001, ten years after Python was designed by Guido van Rossum, and more than ten years ago today, it’s considered the authoritative reference that makes explicit the conventions usually left up to programmers themselves: whether to use tabs or spaces, how many columns to indent by, what kind of naming (lowercase_with_underscores or mixedCaseStyle), and more. The Style Guide goes into great detail, but here I will reproduce the most relevant rules to Python beginners in summary.

Indentation

Depending the default settings of the text editor or IDE you use, pressing the tab key on your keyboard may insert a tab character (a special character indicating an indent) or the equivalent number of plain-old space characters.1 When writing Python, you should configure your editor to use spaces.

In particular, the style guide states that you should use four space characters for an indent.

Line length

The maximum size of a line of Python code should be 79 characters (this includes spaces). This allows people reading any Python code to set their editor window width or terminal emulator width to 80 characters and not have to worry about resizing.2

Whitespace

The Style Guide says it best, so I will quote it directly.

Avoid extraneous whitespace in the following situations:

  • Immediately inside parentheses, brackets or braces.

     Yes: spam(ham[1], {eggs: 2})
     No:  spam( ham[ 1 ], { eggs: 2 } )
    
  • Immediately before a comma, semicolon, or colon.

     Yes: if x == 4: print x, y; x, y = y, x
     No:  if x == 4 : print x , y ; x , y = y , x
    
  • Immediately before the open parenthesis that starts the argument list of a function call.

     Yes: spam(1)
     No:  spam (1)
    
  • Immediately before the open bracket3 that starts an indexing or slicing.

     Yes: dict['key'] = list[index]
     No:  dict ['key'] = list [index]
    
  • More than one space around an assignment (or other) operator to align it with another.

     Yes: 
     x = 1
     y = 2
     long_variable = 3
    
     No:
     x             = 1
     y             = 2
     long_variable = 3
    

Documentation strings

Documentation strings (or docstrings) can be attached to any module (at the top of the .py file), function (after the def line), or class (after the class line). They are simple strings that are better than surrounding comments, since they can be reviewed using Python’s help() function, among other uses. (More information is available in PEP 257, Docstring Conventions.)

Use the triple-double quotation marks (""") to start and end a docstring. The docstring should begin on the line with the opening """, as follows:

def factorial(n):
    """Return the factorial of n."""

If the docstring can’t fit on one line, move the ending """ to its own line after the string and keep writing the docstring. Do not add an extra newline after the opening """. For example:

def replace(secret_word, display_word, letter):
    """Return a list of characters that results from taking the
    existing display word list and revealing any and all occurrences
    of the specified letter, as dictated by secret_word.
    """

Another point to note: PEP 257 states that function docstrings should be a phrase ending with a period that describes the effect of the function as a command, rather than describing it (see the examples above).

Variable, function, and class naming

In summary, the Style Guide states that:

  1. The ASCII tab character is an interesting product of programming history. It was first invented to simulate the tab key originally designed for typewriters. When ASCII was devised in the 60s, the function of the tab key was replaced by a tab character, a character indicating that the characters following the tab character should be prefixed by a number of spaces. But giving the tab character its own spot in the ASCII table meant that an indent could be stored in just one byte — not the bytes that would be required to type out the equivalent number of space characters, so it also resulted in a clever way to save space on the old storage media of the day. Nowadays, there’s no need to use tab characters to save space, and you can configure most text editors to insert four or eight space characters instead of inserting the tab character when you press the tab key. 

  2. The 79-character rule is not arbitrary: like the ASCII tab character (see footnote above), this rule comes from computer science history. IBM was designing punch cards as early as 1928, and their cards were 80 columns wide. This generally remained a convention into the 70s and 80s, when teleprinters and video terminals were invented, most of which allowed the display of 80 columns by 24 or 25 lines. Nowadays, our bitmap displays measure screen resolution in pixels, not characters — and in most cases, we can display much more than 80 columns of text. But limiting the width of an text editor’s window is useful; we can usually place two or more windows next to each other in this case. 

  3. PEP 8 says “open parenthesis,” but this is a typographical error. The punctuation mark is called “left square bracket” or “left bracket.”