Variables and Naming Conventions

Use clear naming and avoid shadowing built-ins to reduce maintenance cost and production mistakes.

On this page

Why Naming Is Operational

Names carry intent. In large codebases, unclear names cause wrong parameter usage and slower incident response.

Conventions

snake_case for functions and variables
PascalCase for classes
UPPER_CASE for constants
_internal prefix for module-private symbols

Do / Don't

# Bad: ambiguous
t = 30

# Good: unit and purpose
timeout_seconds = 30

# Bad: unclear abbreviation
cfg = load()

# Good: reads like a sentence
config = load_config()

Operational Checklist

Names include units when relevant (ms/s, bytes/mb, cents).
Avoid abbreviations unless standardized across the repo.
Do not shadow built-ins like list, dict, id.

Failure Modes

Shadowing built-ins: breaks tools and confuses stack traces.
Ambiguous units: timeouts or sizes are applied incorrectly.

Example: Shadowing

list = [1, 2, 3]  # avoid
dict = {"a": 1}    # avoid

← Running Python Scripts (CLI, Modules, -m)

Strings and f-strings (Real-World Formatting) →