PEP 8 indicates several common standards within Python. Standards also have exceptions, so exercise creativity when needed. To start following Python coding best practices, focus on naming conventions, indentation and comments.

Naming conventions

Python’s library of naming conventions applies to code architecture parts and pieces to which developers assign names. Write all new modules and package names according to the following standards to create consistency and readability:

• Follow an overriding principle for all names. Create names based on usage, rather than what function the code performs. Use descriptive names.
• Common naming convention options in Python include the following:
  • A single lowercase letter or a single uppercase letter in the name. For example, use p or P.
  • All the text in lowercase. For example, write class file as classfile.
  • Snake case, wherein all text is in lowercase with words separated by an underscore. An example is class_file_open.
  • All the text in uppercase. In this example, class file becomes CLASSFILE.
  • A variation on snake case where the text is uppercase with words separated by an underscore: CLASS_FILE_OPEN.
  • CapWords or CamelCase, where the first letter of each word in the name uses uppercase. An example is ClassFileOpen.
  • MixedCase, where the name starts with a lowercase letter and the next word in the name starts with an uppercase letter. Write the example name as classFileOpen.
  • Each word capitalized and separated with underscores. This combination of CamelCase and snake case looks as follows: Class_File_Open.
• Naming conventions can also use the underscore for formatting consistency. Common approaches include the following:
  • A single trailing underscore: single trailing underscore_.
  • Double leading underscore: __boo move –.
  • Double leading and trailing underscore: __boo move__.
• These formatting conventions can cause confusion in specific instances when the letters resemble the integers for 1 and 0. Avoid these naming characters and formatting if possible:
  • Lowercase L (l).
  • Uppercase I (as in Ignore).
  • Uppercase O (as in Oh).
• All identifiers used in a standard library must be ASCII-compatible.
• The Python guidance on package and module names focuses on short names with lowercase letters, relying on other characters where needed for readability. Underscore use for these names is generally discouraged.
• For class names, use the CamelCase style. Use all lowercase letters separated by underscores, like functions, when the primary use is a callable interface.
• For variable names, formatting best practices dictate short type names in CamelCase. Add _co to declare covariant behavior. Add _contra to declare contravariant behavior.
• Global variables are used within a single module only. The __xxx__ with a double underscore before and after indicates a global variable.
• Function names should either appear in lowercase letters and snake case, if it improves readability, or in the mixedCase style, if necessary to retain backward compatibility.
• Name constants on a module level in all uppercase letters and snake case, with underscores between each word.
• Naming conventions can indicate whether an interface is public or internal. Use __all__ attribute to indicate a private or nonpublic API.
• Design for inheritance when naming in Python.
  • Do not use leading underscores.
  • If a public name collides with a reserved keyword, then add a single trailing underscore to the name.
  • For public data attributes, only name the attribute.
  • If a class should be subclassed, name the attributes you don’t want to be subclassed with double leading underscores.

Indentation

Python uses four spaces for each indentation level. For continuation lines, wrap the elements vertically using Python line joining inside parentheses, brackets or braces using a hanging indent. With a hanging indent, don’t use arguments on the first line, and use secondary indentation to distinguish a continuation line.

# Correct:

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

# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

(Credit: PEP 8 Style Guide for Python Code)

If the conditional portion of an if statement occupies multiple lines, use a two-character keyword plus a space, and add an opening parenthesis to create a four-space indent.

# No extra indentation.
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

(Credit: PEP 8 Style Guide for Python Code)

Comments

Developers might call comments a necessary evil. Comments are essential to build a codebase that others can understand. Comments must be written in complete sentences. Review your comments to be sure they are clear and understandable. Ask another developer to interpret the comments. Did they understand your meaning correctly? If not, edit the comments.

Comments must be up to date. If you change the code, update the comments to match the current code function. To follow the PEP-8 guide, write Python code comments in English. Choosing one language for comments ensures transferability.

Python supports multiple comment types, depending on the code structure. Use block comments that are indented in the same manner as the code. Add a # followed by a single space to start comment text. Separate paragraphs within a comment using a single #. If helpful, use inline comments. These comments appear on the same line as a code statement. Separate inline comments from the code statement with two spaces. Start the inline comment with a # and a single space.