Master Python Coding Style: Essential PEP8 Guidelines for Clean Code

1 Code Layout

Use a 4‑space indentation (no tabs) and never mix tabs with spaces. Limit each line to a maximum of 79 characters; line breaks can use a backslash or, preferably, parentheses, with the break occurring after an operator. Separate class and top‑level function definitions with two blank lines, methods within a class with one blank line, and unrelated logical blocks inside functions with a blank line, while avoiding excessive blank lines elsewhere.

2 Documentation Layout

Arrange module content in the order: module docstring → imports → globals & constants → other definitions. Within imports, list standard library modules first, then third‑party modules, and finally local modules, separating each group with a blank line. Avoid importing multiple modules in a single line (e.g., import os, sys is discouraged). When using from X import Y, be aware of potential name conflicts and prefer import X if necessary.

3 Space Usage

Follow the general principle of avoiding unnecessary spaces. Do not place spaces before closing brackets, commas, colons, or semicolons. Do not add a space before a function’s opening parenthesis (e.g., Func(1)) or before a sequence’s opening bracket (e.g., list[2]). Use a single space around operators, avoid extra spaces for alignment, and omit spaces around the equals sign in default parameter values. Write each statement on its own line; even if a loop or conditional contains a single statement, place it on a new line.

4 Comments

Comments should be in English, written as complete sentences with proper capitalization and punctuation. When code changes, update the corresponding comments immediately. Block comments precede a code block, start with # followed by a space, and are separated from other comments by a line containing only #. Inline comments (after a line of code) are allowed but should be used sparingly. Avoid redundant comments.

# Description : Module config.
# 
# Input : None
#
# Output : None

Example of an inline comment:

x = x + 1  # Increment x

5 Documentation Description

Write docstrings for all public modules, functions, classes, and methods; private members may omit docstrings but can still have comments directly after the def line. For multiline docstrings, follow PEP 257 conventions.

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.

"""

6 Naming Conventions

Adopt consistent naming styles: avoid confusing characters like lowercase l and uppercase O. Use short, all‑lowercase module names with underscores if needed; package names should be short, all lowercase, without underscores. Class names use CapWords; internal classes may use a leading underscore ( _CapWords). Exception classes use CapWords followed by Error. Global variables should be limited to the module scope, using the __all__ mechanism or a leading underscore. Function names are lowercase with optional underscores; constants are uppercase with underscores. Attribute names follow the same lowercase‑with‑underscores rule. Attribute visibility follows public, non‑public (single leading underscore), and subclass‑API (double leading underscores) conventions. Methods receive self as the first parameter; class methods receive cls.

7 Coding Suggestions

Consider performance across Python implementations: use .join() instead of repeated string concatenation, as the + operator is fast in CPython but slower in Jython. Prefer is and is not over == for identity checks (e.g., if x is not None). Define module‑specific exception classes inheriting from Exception. Avoid bare except clauses; catch specific exceptions. Keep try blocks minimal:

try:
    value = collection[key]
except KeyError:
    return key_not_found(key)
else:
    return handle_value(value)

Prefer startswith() and endswith() over slicing for prefix/suffix checks, and use isinstance() for type comparisons. Test sequence emptiness with if not seq: or if seq: rather than checking length. Avoid trailing spaces in strings and use boolean checks for binary data.