principle-minimize-reader-load

Measure reader load on two axes: layers of indirection between a question and its answer, and hidden mutable state the reader must track. Collapse wrappers with one caller, inline pass-through adapters, and shrink state scope from globals toward locals and pure functions.

Identify layers that do not earn their keep: wrappers with a single caller, adapters with no second implementation, and indirection added for a future that never arrived. Inline them, and require that each remaining layer changes the abstraction rather than repeating the same methods.

Keep a layer when it provides interface compression, hiding meaningful decisions behind a narrow boundary. Remove it when it merely repeats the same methods and arguments, since pass-through layers add reader load without reducing complexity.

Cyclomatic complexity counts decision paths, while reader load measures the work a human does to understand code: indirection layers to trace and hidden state to hold. A flat file with fifty globals can be as hard to reason about as a six-layer adapter stack.

Prefer pure functions that return values over mutations, locals over fields, fields over module state, and module state over globals. Derive values instead of synchronizing them, and name invariants once at the boundary rather than in every consumer.