principle-minimize-reader-load

• SKILL.mdcore · 2,968 bytes

# Minimize reader load

Measure maintainability by how hard a reader must work to understand the code. Two separate axes set that effort: the number of hops between a question and its answer, and the amount of hidden or changeable state the reader has to keep in mind.

## When it applies

Reviewing or shaping hard-to-follow code, deciding whether new indirection or new state is justified, and writing anything people will read, including verdicts and reports. It is a lens you always hold, not a procedure with preconditions.

## What to do

1. Treat line counts, cyclomatic complexity, and architectural tidiness as proxies. Reader effort is the target.
2. Guard both axes. They vary independently. A flat file full of globals can be as hard to read as a deep stack of adapters.
3. Delete layers whose cost exceeds their benefit: wrappers with one caller, interfaces with one implementation, and indirection added for a future that never came. Inline them.
4. Require each layer to change the abstraction. A layer that forwards the same methods with the same arguments is pass-through, so collapse it.