Essential Python Coding Style Guide: Simple Rules for Clean Code

0. Introduction

This article summarizes the most essential and straightforward Python coding conventions, offering a simple, practical set of rules that can be adapted to personal preferences.

1. Important Principles

a. Consistency in style is important, but the most crucial aspect is knowing when to break consistency. b. Two good reasons to break an established rule: • When following the rule reduces code readability. • To stay consistent with surrounding legacy code.

2. Simplest Rules

Use spaces for indentation only.

Use UTF‑8 encoding.

Write only one statement per line.

Fold long lines with a trailing backslash, limiting each line to 79 characters.

Import statements: one per line, ordered from standard library to third‑party to local packages, using absolute imports.

Separate class methods with one blank line; separate top‑level functions/classes with two blank lines.

Place a single space around operators except the asterisk (*); no spaces around the equals sign in function arguments.

Use lowercase with underscores for modules, functions, methods, and variables; use CamelCase for class names.

One leading underscore denotes “protected” (semi‑private); two leading underscores denote “private”; a trailing underscore avoids conflicts with reserved words.

Write comments in Chinese during development, and provide English documentation for release.

3. Detailed Rules

Use spaces for indentation, with four spaces per level.

Limit line length to 79 characters, using a trailing backslash to fold longer lines.

Use UTF‑8 encoding.

One statement per line.

4. Naming Conventions

Import one package per line; order imports as standard library, related major packages, then specific applications, separating groups with a blank line and using absolute paths.

Separate top‑level function and class definitions with two blank lines; separate methods within a class with one blank line; place one blank line between the class definition line and its first method.

Write spaces after commas and semicolons only; do not insert spaces inside parentheses, brackets, or braces. Use a single space around all operators except the asterisk (*). Do not add spaces around the equals sign in function arguments.

Module names: short, all lowercase, without underscores. Class and exception names: CamelCase. Function, global variable, method, and instance variable names: lowercase with underscores. A single leading underscore marks non‑public globals, internal functions, classes, methods, and instance variables. Two leading underscores indicate class‑private names to avoid name clashes. Private attributes must have two leading underscores and no trailing underscore. Non‑public attributes have one leading underscore and no trailing underscore. Public attributes have no leading or trailing underscores unless they clash with reserved words, in which case a trailing underscore is preferred (e.g., class_ over klass).

5. Coding Tips

Compare singletons like None with is or is not (e.g., if x is not None:).

Define a base exception class in each module or package.

Prefer string methods over the string module.

Use startswith() and endswith() instead of slicing for prefix/suffix checks.

Use isinstance() for type checking rather than comparing types directly.

Do not compare booleans with ==; write if greeting: instead of if greeting == True:.

6. Comments

Write comments in Chinese during development; provide English documentation for released scripts.

Comments should be complete sentences (or short phrases) with an initial capital letter; omit the final period for very short comments. Block comments consist of one or more full sentences, each ending with a period and two spaces after the period.

Start each comment line with # followed by a space, matching the indentation of the associated code, and surround comment blocks with a blank line above and below.

Use inline comments sparingly, separating them from code with at least two spaces.

Document public modules, functions, classes, and methods with docstrings using tools like pydoc, epydoc, or Doxygen. Non‑public members need not have docstrings, but a brief comment describing the method’s purpose should follow the def line.

Terminate multi‑line docstrings with a closing triple‑quote on its own line.

Version Note

Define a variable __version__ = "$Revision: 1.4 $".

Stay hungry. Stay foolish.