Python Code Style Guidelines

This document outlines the core principles I value in a code base to ensure maintainability and readability. They don't apply to every code base, and are highly opinionated.

These guidelines are somewhat inspired by Clean Code principles by Robert C. Martin. They go along with the Zen of Python.

DRY (Don't Repeat Yourself)

• ... unless you can't come up with meaningful names for the abstraction (yes… really.).
• Every line of code is a liability.

Naming

• The meaningfulness of a name must be proportional to its scope.
  • Variables with larger scopes deserve more descriptive names.
  • Short-lived variables in small scopes can have short names.

Readability or performance?

• Readability is the correct answer.
  • In large scopes, prioritize readability.
  • In small scopes, you can choose performance.

Functions

• must have the least possible amount of arguments (AND avoid passing complex structures!).
• must always* return 1! thing.
• must be intuitive in their naming and behavior.

Variables

• Declation must be as close to where it is used as possible.
• No top-of-function declarations for normal variables.

Imports

• Least possible amount of imports: Be intentional about dependencies.

Comments

• Prefer self-explanatory code over comments. Write code that reveals its intent through clear naming and structure. Add comments only when:
  • Explaining "why" something is done a certain way, not "what" is being done
  • Documenting complex algorithms or statistical methods that aren't immediately obvious
  • Providing context for data-specific operations that might not be familiar to all team members

Crashing

• Better to crash than to skip something
  • Avoid using logger.exception without proper handling.
  • Avoid nested try - except.

Updating code

• When updating code, try to keep your diff as small as possible so that we can browse the history of the file easily.