A Five-Minute Introduction to Python’s Style Guide: PEP 8

Readability counts

PEP — short for Python Enhancement Proposal — is a list of documents that either propose new features or conventions for the language. One of these, PEP 8, is a living document of style conventions for writing Python.

Before we get too deep, your code will still work if you don’t adhere to PEP 8 guidelines. However, since the majority of the Python community follows these rules, adopting them will improve your reading speed; plus you should find they make it easier to read your own code.

Guido van Rossum — the author of Python — proposed PEP 8 explicitly to improve the readability of code and create a consistent experience. A key insight of his was that code is read much more often than it is written. Thus, readability counts.

https://www.python.org/dev/peps/pep-0008

Below are four quick summaries of PEP 8 topics intended to give you actionable next steps in your Python code.

Naming Conventions

If you take away nothing else from this guide, the naming conventions you use will play a tremendous role in how well or poorly your code reads. It is also the single easiest improvement you can make.

  • For variables, use lowercase letters and underscores to separate words.

  • For functions, use lowercase letters and underscores to separate words.

  • For classes, capitalize the first letter of each word — called CapWords or CamelCase.

  • For constants, use all capital letters and underscores to separate words.

  • Avoid using overly abbreviated names such as fn; write out first_name instead.

  • Never use lowercase ‘L’, uppercase ‘O’, or uppercase ‘I’ as variable names, they are too easily confused with a 1 or 0.

Indentation

Since Python uses indentation in lieu of curly braces to denote block ownership, it is critical to have clean and consistent indentation style. Guidelines are not overly strict, often giving multiple options; however, the critical takeaway is to pick a convention and stick with it.

PEP 8 clearly puts a stop to the spaces vs tabs argument, recommending four spaces instead of a tab character.

Let’s go through some of the main conventions and their competitors.

Opening Delimiter vs Hanging Indent

For longer lists of values, either indent based on the opening delimiter or use a hanging indent. When using hanging indents, no values should exist on the first line and the indentation is one level deeper if there is an ensuing block.

# Opening Delimiter
result = my_function(first_argument, second_argument,
                    third_argument, fourth_argument)
# Hanging Indent
result = my_function(
    first_argument, second_argument,
    third_argument, fourth_argument)
def my_function(
        first_argument, second_argument,
        third_argument, fourth_argument):
    print(first_argument)

Whitespace or First Character Alignment

For multiline constructs, the closing symbol can be aligned with the used whitespace or with the first character of the statement.

# Whitespace alignment
my_list = [
    1, 2, 3,
    4, 5, 6,
    ]

# First Character Alignment
my_list = [
    1, 2, 3,
    4, 5, 6,
]

Whitespace and Line Breaks

PEP 8 has pretty strict guidelines on when to split long lines and add whitespace. Don’t stress over being perfect here, there are tools to format your code if/when you get that serious. Use the following as a starting point, but most importantly: stay consistent.

  • Use two blank lines for top-level function/class definitions and one blank line for method definitions.

  • Optionally use a blank line to separate logical steps in longer sequences.

  • Avoid excessive whitespace immediately inside of parenthesis, brackets, or braces. bad_spacing = { 1 }

  • Use whitespace around assignment and logical operators.

  • Use whitespace to communicate order of operations. x = 2*y + 2*z

  • Keep lines under 79 characters — this is intended to minimize line-wrapping on side-by-side windows.

Single Quotes or Double Quotes

Both single and double quotes are used when defining string values. Additionally, triple quotes are used for multiline strings. Python does not advocate for single or double quotes, but does provide usage guidelines.

  • Use double quotes for strings with an apostrophe.

  • Use single quotes for strings with quotation marks.

  • Always use double quotes for multiline strings.


Do not let these guidelines get in the way of learning Python. However, just like anything else, it’s easier to learn something right the first time compared to breaking a bad habit.

View comments