/pystyleguide

Guidelines to produce clean and maintainable Python code

Creative Commons Zero v1.0 UniversalCC0-1.0

Python Code Style Guide

Principles

  1. PEP-8 Style Guide for Python Code
  2. Explicit is better than implicit
  3. Do not repeat yourself
  4. Keep things simple
  5. Keep things intuitive
  6. SOLID
  7. The Twelve-Factor App

Code

  1. Always prefer code maintainability and readability even if this might sacrifice some performance.
  2. Google Python Style Guide
  3. Keep functions and methods ideally less than 25 lines.
  4. Maintain methods lowest cyclomatic complexity: avoid if statements when possible (write branchless code), never use nested if. Be Never Nester.
  5. Don't concatenate strings with + it's unprofessional, error-prone, slower, and might be confusing, prefer f-string or "".join().
  6. The lesser indent your code has, the better.
  7. Use isort, and black to format your code.
  8. Use pylint, and mypy to check your code.

Method signature

  1. A method signature where the order of arguments "does not matter" (e.g. args are the same type) or the order is obvious is good for positional arguments:
def add(a: float, b: float) -> float: ...
  1. A method that expects non-interchangeable arguments is a good case to enforce keyword arguments, which will remove any ambiguity or wondering what should come first when calling the method:
def set_token(self, *, domain: str, token: str, expires_in: int) -> None: ...
  1. For a method around something you can combine positional and keyword arguments, using one positional for "something" and keyword arguments for everything else:
def get_instance(self, instance_id: int, *, include_inactive: Optional[bool] = False) -> T: ...