PEP 8 Guidelines: Essential Tips for Clean Python Code

The PEP 8 guidelines are an essential aspect of writing clean and readable Python code. Developed in 2001 by Guido van Rossum, Barry Warsaw, and Nick Coghlan, these guidelines focus on enhancing the readability and consistency of Python code for all programmers.

💡 PEP 8, which stands for Python Enhancement Proposal 8, has significantly contributed to the Python programming community by establishing a shared set of best practices that make it easier for developers to collaborate and understand each other’s work. These guidelines cover a range of coding practices, from indentation and whitespace usage to naming conventions and commenting.

It is worth noting that while following PEP 8 guidelines is crucial, consistency within a particular project is even more important.

PEP 8 Overview

PEP 8 is a widely recognized style guide for Python code, which provides guidelines and best practices on how to write readable and consistent Python programs. Introduced in 2001 by Guido van Rossum, Barry Warsaw, and Nick Coghlan, the primary focus of PEP 8 is to help Python developers maintain a consistent coding style across the entire community.

PEP 8 covers multiple aspects of Python code style, such as naming conventions, indentation, line length, and whitespace.

One of the key principles of PEP 8 is the use of consistent indentation, typically with four spaces per indentation level. This helps organize the code, making it more structured and maintainable.

Another important aspect is the separation of statements and expressions with spaces, ensuring that the code remains clear and easy to follow.

Furthermore, PEP 8 provides guidance on naming conventions for variables, functions, and classes, promoting the use of meaningful names and consistent capitalization patterns.

For instance, function names should be lowercase with words separated by underscores, while class names should use the CapWords convention.

The Python Style Guide also emphasizes the importance of writing concise and self-descriptive code. Python developers are encouraged to write short, modular functions that perform a single task, and to use clear and descriptive comments for better code understanding.

Code Layout

PEP 8 guidelines place a high emphasis on the code layout to ensure consistent and readable Python code. A well-structured layout comprises several key elements, such as indentation, line length, and trailing commas.

Indentation

Indentation is a crucial aspect of a proper code layout in Python. According to the PEP 8 guidelines, programmers must use four spaces per indentation level for clarity.

def some_function():
    for i in range(5):
        print(i)  # Indented with 4 spaces

It is essential to avoid mixing tabs and spaces for indentation, as this can lead to confusing and unreadable code.

Spaces

Spaces are preferred for readability.

# Correct
spam(ham[1], {eggs: 2}, [])

# Wrong
spam( ham[ 1 ], { eggs: 2 }, [ ] )

PEP 8 recommends using spaces over tabs for a consistent appearance across different development environments and tools.

Maximum Line Length

Another vital factor in code layout is line length.

PEP 8 suggests keeping the maximum line length at 79 characters. This constraint improves readability on small screens and allows for side-by-side editing on larger screens.

# This is okay
with open('/path/to/some/long/directory/and/filename.txt', 'rb') as file:
    file.write(some_content)

When a line exceeds the 79-character limit, it is recommended to use line wrapping and adhere to the hanging indent style.

Hanging Indent

PEP 8 suggests using hanging indentation for line continuation.

# Aligned with opening delimiter
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Hanging indents should add a level
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

Hanging indents involve aligning wrapped elements either with parentheses or using indentations of four spaces.

Binary Operator

In some cases, a line of code may include a binary operator. According to PEP 8, it is recommended to place the binary operator at the beginning of the new line, improving readability by clearly showing the relationship between the operands.

# Correct:
total = (first_variable
         + second_variable
         - third_variable)

# Wrong:
total = (first_variable +
         second_variable -
         third_variable)

Trailing Commas

Trailing commas play a significant role in the code layout as well.

The PEP 8 guidelines propose using trailing commas in various instances, such as when listing items in tuples, lists, and dictionaries spanning multiple lines.

my_list = [
    'item1',
    'item2',
    'item3',  # This trailing comma is allowed in Python
]

The use of trailing commas can lead to cleaner diffs and prevent common syntax errors when adding or removing elements.

TLDR: Adhering to the PEP 8 guidelines for code layout, such as indentation, spaces, maximum line length, hanging indent, binary operator, line wrapping, and trailing commas, ensures a confident, knowledgeable, and clear code structure.

Whitespace and Formatting

When writing Python code, following PEP 8 guidelines for whitespace and formatting ensures readability and consistency. Proper utilization of whitespace is crucial for enhancing the clarity of code and making it easier to understand.

PEP 8 emphasizes the importance of whitespace around expressions and statements. In most cases, it is recommended to surround binary operators with a single space on either side.

For example, use x = x * 2 - 1 rather than x=x*2-1.

When dealing with assignment operators, it is advised to use spaces around low-priority operators.

For instance, consider writing x = x * 2 - 1 instead of x=x*2-1.

Another critical aspect of PEP 8 guidelines is indentation. The standard recommendation is to use four spaces per indentation level. Mixing spaces and tabs should be avoided, and a single indent should have the same amount of spacing throughout the project.

When it comes to line length, PEP 8 advises limiting lines to a maximum of 79 characters. This is because longer lines can be challenging to read and may not display properly on all devices.

If the line exceeds this length, consider breaking it down and using parentheses or a backslash to create a more concise and readable expression.

In terms of source file encoding, PEP 8 recommends using UTF-8 as the default encoding for Python source files. This ensures compatibility with a wide range of characters while maintaining ASCII compatibility.

Using UTF-8 encoding supports internationalization and improves the code’s accessibility for developers from different linguistic backgrounds.

Naming Conventions

Regarding functions, PEP 8 recommends using lowercase names, with words separated by underscores. For example, get_name() or update_db(). This format is easy to read and understand.

Methods should follow the same convention as functions.

Classes should have names that follow the CapWords or PascalCase convention, meaning each word is capitalized without underscores separating them. For example, Person, TruckDriver, or DatabaseManager are all valid class names.

When it comes to module names, PEP 8 advises using short, lowercase names, and underscores can be used when it enhances readability. For example, sys, os, and http_client are all appropriate module names.

When defining variables in Python, PEP 8 recommends using lowercase names with words separated by underscores, such as first_name and total_amount. This convention makes it easy to identify variables within the code.

Constants should be named using all uppercase letters with underscores separating words. For example, MAX_SPEED or API_KEY are suitable names for constants.

Additionally, PEP 8 urges developers to avoid using names that might create confusion between different entities. For instance, lowercase 'l' and uppercase 'O' should be avoided as they resemble the numbers '1' and '0', respectively.

Comments and Docstrings

PEP 8 provides guidelines for writing clear and concise comments and docstrings in Python code.

Comments

Comments are an essential part of any codebase. They help to explain the purpose, functionality, and reasoning behind a specific section of code. In Python, comments are denoted by the hash symbol (#).

According to PEP 8, comments should be complete sentences and properly capitalized. They should be brief, but informative. It’s also important to keep comments up-to-date as code evolves, to avoid confusion.

Docstrings

Docstrings, on the other hand, are a more formal way of documenting Python code. They are used to provide a description of a module, class, or function.

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. It is enclosed in triple quotes, either single (''') or double ("""). PEP 8 recommends using double quotes for consistency.

PEP 257 is an extension of PEP 8, focusing specifically on docstring conventions. It standardizes the high-level structure of docstrings, outlining what they should contain and how to express it. One of its primary goals is to encourage developers to write clear and concise docstrings for their Python code.

PEP 8 encourages consistency between comments and docstrings. Both should use a neutral, clear, and concise tone. Moreover, both should be written in a third-person point of view. Writing in this manner helps to make the code’s documentation feel more knowledgeable and objective.

Imports and Modules

When importing modules, it is important to follow PEP 8’s recommendation of placing imports at the beginning of the file, before any other code. This makes it easier to understand the dependencies of the code at a glance.

The guide also advises against using wildcard imports (e.g., from module_name import *), as they can lead to name clashes and make it unclear which variables and functions belong to which module.

In terms of order, PEP 8 suggests separating imports into three groups, with a blank space between each group:

Standard library imports
Third-party imports
Local application/library-specific imports

Consider the following example:

import os
import sys

import numpy as np

import local_module

In this example, the standard library imports (os and sys) are first, followed by the third-party import (numpy), and finally, the local application-specific import (local_module).

Regarding module names, PEP 8 recommends using all lowercase letters and separating words with underscores. This makes module names easy to read and understand. Package names should also follow these guidelines, though they can be shorter and use single underscores. Avoid using reserved words as module or package names, as this can lead to confusion.

Another best practice is to avoid using relative imports when it is possible, as they can be ambiguous and lead to unexpected behavior.

For multiple imports from a single module, PEP 8 suggests placing each import on a separate line, for example:

from module_name import function_a
from module_name import function_b

This approach enhances code readability and makes it clear which functions are being imported.

By adhering to PEP 8’s guidelines for imports and modules, developers can create more readable, consistent, and maintainable Python code.

Function and Method Definitions

Python’s PEP 8 guidelines provide clear recommendations on how to write function and method definitions in a consistent and readable manner. Functions and methods are defined using the def keyword, followed by the function or method name, a pair of parentheses enclosing the arguments, and a colon.

Function names should follow the standard naming convention of being lowercase, with words separated by underscores. This helps to improve readability and maintain consistency throughout your code.

For example:

def example_function(argument1, argument2):

Function annotations can be used to provide additional information, such as the expected data types for arguments and the return type. Annotations are optional, but they can be helpful for documenting your code and improving its readability.

Here’s an example using annotations:

def example_function(argument1: int, argument2: str) -> float:

In this example, the function takes an integer and a string as arguments and returns a float. Note that PEP 8 does not enforce a specific style for annotations, but they should be used consistently within a project if implemented.

In the case of methods, it’s important to remember that the first argument should always be a reference to the instance of the class (usually named self).

Here’s an example of a method definition within a class:

class MyClass:
    def example_method(self, argument1, argument2):

When defining a method, remember to use the same naming conventions as with functions, keeping the method names lowercase with words separated by underscores.

Classes and Inheritance

In Python programming, following the PEP 8 guidelines for classes and inheritance leads to more readable, consistent, and maintainable code. Developers need to adhere to these guidelines when creating classes and working with inheritance in their projects.

✅ Recommended: Introduction to Python Classes

When defining a class, use the CapWords (also known as PascalCase) convention for naming. This means combining uppercase and lowercase letters, with the first letter of each word being uppercase.

For example, a class named MyClass follows this convention.

It’s important to carefully decide whether a class’s methods and attributes should be public or non-public.

PEP 8 recommends choosing non-public if in doubt, as it’s easier to make a non-public attribute public later on if needed. Designing with the principle of least privilege in mind ensures minimal exposure of a class’s inner workings.

To indicate that an attribute is intended to be non-public, prefix it with an underscore (_). For instance, _my_attribute would signify a non-public attribute. However, it’s crucial to understand that this is just a convention and does not enforce strict encapsulation.

Inheritance is a powerful feature in Python, allowing classes to share and reuse code. When designing for inheritance, it’s important to follow the PEP 8 guidelines for maximum code clarity. Be aware of the distinction between single and multiple inheritance and use them appropriately in your code.

Avoid using multiple inheritance if mix-in classes can achieve the desired behavior. Mix-ins are small, highly focused classes that can be combined to create more complex classes. This often leads to cleaner and more manageable code compared to using multiple inheritance.

When dealing with subclasses, developers should minimize external dependencies on a class’s inherited behavior. This helps maintain a clear and understandable codebase, lowering the risk of unintended consequences when making modifications in the future.

Special Considerations for Python 3

Python 3, being a major version release, brought about some important changes and improvements over Python 2. PEP 8 guidelines remain crucial in maintaining readability and consistency in Python 3 code, but there are some special considerations when moving from Python 2 to Python 3.

Firstly, it is essential to ensure backwards compatibility wherever possible. Python 3 introduced several updates that might break compatibility with Python 2 if not handled carefully.

Some of the major changes include changes in syntax, division behavior, and string handling.

To maintain readability in Python 3, developers should make use of the print() function instead of the print statement prevalent in Python 2. This change provides a consistent interface with other functions and enhances readability.

Moreover, when handling exceptions, developers are strongly encouraged to use the new as keyword in Python 3, which simplifies the syntax for catching exceptions.

Unicode handling in Python 3 has been significantly improved. While in Python 2 strings were either ASCII or Unicode based on how they were defined, Python 3 treats all strings as Unicode by default.

This change enhances readability and reduces the risk of encoding errors. It is recommended that developers include the following import statement at the beginning of their Python 3 files to ensure consistent Unicode behavior: from __future__ import unicode_literals.

Readability and Consistency

The PEP 8 style guide emphasizes the importance of readability, stating that “Readability counts”.

One key aspect of PEP 8 is its focus on using descriptive names for variables, functions, and classes. These names should represent the purpose or functionality of the code element, making it easier for programmers to understand the role of each component in the codebase.

For instance, instead of using ambiguous names like a or x, PEP 8 recommends adopting meaningful names like filename or input_data.

In addition to naming conventions, PEP 8 emphasizes the consistent use of code formatting and whitespace. Consistency includes proper indentation, avoiding extraneous spaces, and using blank lines to separate functions and classes.

Another essential aspect of PEP 8 involves programming recommendations that focus on writing efficient and robust Python code. These recommendations cover various topics, such as avoiding the use of global variables, using list comprehensions instead of map() and filter() functions, and preferring is or is not over == when testing for object identity.

Miscellaneous Conventions

PEP 8 recommends several miscellaneous conventions for making Python code more readable and consistent. This section presents a few, focusing on identifiers, dunder names, string quotes, exception names, global variable names, closing braces, and closing parentheses where relevant.

Regarding identifiers, PEP 8 encourages the use of clear, descriptive names and underscores for readability. For instance, use snake_case for functions, variables, and methods, where words are separated by underscores. Constants should be declared using UPPER_CASE_WITH_UNDERSCORES.

Dunder names, or double underscore names, are reserved by Python, and PEP 8 advises developers to avoid using names with double leading and trailing underscores (__example__), unless they are using standard Python attributes or methods like __add__ or __init__.

In terms of string quotes, PEP 8 does not enforce a specific choice between single or double quotes. However, it is important to stay consistent within the project. Developers should adhere to the chosen style throughout the codebase, only deviating when it’s necessary to avoid escaping characters.

When it comes to exception names, PEP 8 recommends developers to append the word “Error” to their custom exception classes. This makes it evident that a class is designed for use as an exception.

For global variable names, PEP 8 suggests that they be declared using the same snake_case convention as other variables. However, they should be documented in a module-level comment to clearly indicate their purpose and usage.

When writing code with closing braces and parentheses, PEP 8 specifies that they should be placed where they align with the first non-whitespace character of the previous line. For example:

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'argument1', 'argument2', 'argument3',
    )

In this example, the closing brackets and parentheses are aligned with the first character of the lines they opened, adhering to PEP 8 recommendations.

PEP Implementation in Python

Various tools can assist developers in adhering to PEP 8 best practices. These tools, such as flake8, pylint, and autopep8, can automatically analyze and even fix code to ensure it follows the recommended conventions.

Resources and Further Reading

To delve deeper into PEP 8 guidelines, a variety of resources exist that could provide valuable insights and help enhance your Python coding skills.

One essential resource to explore is the official PEP 8 document on peps.python.org. This comprehensive guide contains guidelines on coding style, formatting, and readability to improve consistency across Python code.

Another resource worth checking out is pep8.org, a stylized presentation of PEP 8 created by Kenneth Reitz (for humans). This website offers an easy-to-read and user-friendly version of the official PEP 8 document.

For those looking to expand their understanding of PEP 8 and its best practices, consider reading How to Write Beautiful Python Code With PEP 8 on Real Python. This article covers PEP 8’s primary focus, its advantages, and how to apply it to your Python code for improved readability and consistency.

Another helpful article for getting started with PEP 8 is the Python PEP 8 tutorial on Educative. This tutorial offers an overview of PEP 8’s importance and demonstrates its usefulness in elevating your code-writing process.

Finally, consider reading An Overview of The PEP 8 Style Guide on Towards Data Science. This article provides an introduction to the comprehensive styling guide, its purpose, and recommendations for adopting it in your Python projects.

Frequently Asked Questions

What is the recommended maximum line length in PEP 8?

According to PEP 8, the recommended maximum line length for code is 79 characters, and for docstrings and comments, it is 72 characters. This helps improve readability and maintainability of the code.

How do PEP 8 guidelines affect docstrings?

PEP 8 guidelines suggest that docstrings should be written using triple double quotes("""). They should also follow the PEP 257 conventions for consistency and readability. This includes having a one-line summary, more detailed description (if necessary), and proper formatting for parameters and return values.

Are there tools available for checking compliance with PEP 8?

Yes, there are tools available for checking compliance with PEP 8. Some popular tools include pycodestyle, flake8, and black. These tools can help you identify and fix any PEP 8 non-compliance issues in your code.

Is adherence to PEP 8 mandatory or optional?

Adherence to PEP 8 is not mandatory. However, it is highly recommended to follow these guidelines for consistency and readability across Python projects. Remember, consistency within a project is more important than being consistent with the PEP 8 style guide itself.

What are the differences between PEP 8 and PEP 257?

While PEP 8 focuses on providing style guidelines for the overall Python code, PEP 257 focuses specifically on providing conventions for writing docstrings in Python. PEP 257 offers guidance on how to format and structure docstrings, whereas PEP 8 offers more general style guidance for writing Python code.

How can I configure my Visual Studio Code to follow PEP 8?

To configure Visual Studio Code to follow PEP 8, install the Python extension and a compatible linting tool like pycodestyle or flake8. After installation, open the settings in your VSCode, go to the Python section and update the python.linting.pycodestyleEnabled or python.linting.flake8Enabled setting to true. You may also customize linting configurations to suit your project requirements.

Related Articles:

The Art of Clean Code

Most software developers waste thousands of hours working with overly complex code. The eight core principles in The Art of Clean Coding will teach you how to write clear, maintainable code without compromising functionality. The book’s guiding principle is simplicity: reduce and simplify, then reinvest energy in the important parts to save you countless hours and ease the often onerous task of code maintenance.

Concentrate on the important stuff with the 80/20 principle — focus on the 20% of your code that matters most
Avoid coding in isolation: create a minimum viable product to get early feedback
Write code cleanly and simply to eliminate clutter
Avoid premature optimization that risks over-complicating code
Balance your goals, capacity, and feedback to achieve the productive state of Flow
Apply the Do One Thing Well philosophy to vastly improve functionality
Design efficient user interfaces with the Less is More principle
Tie your new skills together into one unifying principle: Focus

The Python-based The Art of Clean Coding is suitable for programmers at any level, with ideas presented in a language-agnostic manner.

Get on Amazon!