Python coding style

python-code-style.md

Coding style

Follow these rules below.

General style

Follow PEP 8.

As a summary:

• Indent with 4 spaces.

• Follow Python naming conventions:

  • lower_case_with_underscores for modules, functions, methods and variables.
  • UPPER_CASE_WITH_UNDERSCORES for constants.
  • CapitalizedWords (initial uppercase letter) for class names.
  • mixedCase (initial lowercase letter) for method names.
  • _single_leading_underscore for internal functions, methods or variables.
  • single_trailing_underscore_ to avoid conflicts with Python vocabulary. E.g., class_, list_, etc.
  • Avoid confusing names.

Personal opinion:

• Use double quotes for strings. Unless there's a double quote inside the string.
• Line length of 88 characters.
• Name disposable variables as __ (double underscore).
• Use one-letter variable names in small contexts; i.e, in a list comprehension, inside a lambda, small function or inside a for loop.
• Use one-letter variable names for their canonical meaning:
  • c for character.
  • s for string.
  • i, j and k for indexes.
  • n and m for numbers.
  • x, y and z for coordinates.

Personal recommendations:

1. Indent code automatically with Black:

   $ cat myscript.py | black --quiet --target-version py37 -
   

2. Organize imports automatically with isort:

   $ cat myscript.py | isort --quiet -
   

Comments

Do your best to give meaningful names to modules, classes, functions and methods and avoid comments.

When this is not sufficient, read the section about it in PEP 8.

Use comments sparingly to explain why, not how.

Comments that contradict the code are worse than no comments.

Following Strunk & White's The Elements of Style:

• Use active voice.
• Be precise.
• Be clear.
• Be concise, i.e., omit useless words.

Docstrings

Follow Strunk & White (read above, in Comments).

Follow PEP 257:

• Use """triple double quotes""" around docstrings.

• Use r"""raw triple double quotes""" if you use any backslashes in your docstrings.

• Write 72 characters per line inside a docstring.

Examples:

• One-line docstring

  def func():
      """This is a one-line docstring."""
      ...
  

• Multi-line docstrings

  def func():
      """Summary line, an overview of what "func" does.
      
      Multi-line docstrings consist of a summary line just like a 
      one-line docstring, followed by a blank line, followed by a more
      elaborate description.
      """
      ...
  

Personal recomendation: use docformatter to format docstrings:

$ cat myscript.py | docformatter --pre-summary-newline -

.end.