principle-minimize-reader-load

Count two things: the layers between a question and its answer, and the hidden state a reader must track. Collapse wrappers with one caller and pass-through layers, and shrink mutable scope from globals toward locals and pure functions.

A layer earns its keep only if it changes the abstraction or hides meaningful decisions. If it repeats the same methods and arguments as the layer below, or exists for a future that never came, inline it.

Cyclomatic complexity counts branches; reader load measures the work a human does to trace code. A flat file with 50 globals can be harder to reason about than a layered design, so both layers and state scope must be guarded independently.

Keep a layer when it has multiple callers or implementations, hides a meaningful decision, or names an invariant at a boundary so consumers learn it once. Collapsing such layers increases reader load elsewhere instead of reducing it.

Prefer returns over mutations, locals over fields, fields over module state, and module state over globals. Derive values instead of synchronizing copies, so readers can answer "what can change X?" quickly.