Core readability rules
- Reduce the layers a reader must trace.
- Prefer direct flow over indirection.
- Avoid unnecessary wrappers, abstractions, and pass-through helpers.
- Inline logic when the abstraction does not remove real complexity.
- A reader should not need to jump across many files or functions to understand the main path.
- Reduce the state a reader must hold in their head.
- Keep functions small and locally understandable.
- Minimize mutable state.
- Prefer explicit inputs and outputs over hidden dependencies.
- Avoid temporal coupling: the meaning of code should not depend on steps that happened far earlier.
- Keep naming and control flow predictable.
When choosing between two implementations, prefer the one that:
- is understandable with fewer mental jumps
- requires tracking fewer variables, flags, and implicit assumptions
- makes the happy path obvious
- keeps cause and effect close together
Do not add abstraction unless it clearly removes more complexity than it creates. Do not optimize for cleverness. Optimize for local reasoning.
=== summary ===
Favor local reasoning over abstraction. Minimize the layers a reader must trace. Minimize the state a reader must hold in their head. Prefer explicit, direct code over clever indirection.