principle-minimize-reader-load
最小化读者负担
Maintainability is the work a reader must do to understand code. Track two axes:
- Layers to trace. How many indirections sit between the question and the answer.
- State to hold. How much hidden or mutable context the reader must keep in their head.
可维护性是读者理解代码必须付出的劳动。盯两轴：
- 要追的层。 问题与答案之间有多少间接。
- 要端着的状态。 读者脑中要留多少隐藏或可变上下文。
Why: Code is read far more than it is written. LOC, cyclomatic complexity, and “clean architecture” are proxies. Reader load is the thing that matters. The two axes are independent. A flat file with 50 globals can be as hard to reason about as a 6-layer adapter stack. Guard both. This is the human analog of Guard the Context Window. Working memory is finite for readers too.
为什么： 代码读远多于写。LOC、圈复杂度、「干净架构」都是代理指标。要紧的是读者负担。两轴独立。一个塞满 50 个全局的扁平文件，可以和 6 层适配器栈一样难推理。两边都守。这是 Guard the Context Window 的人类版。读者的工作记忆也有限。
The pattern:
模式：
-
Collapse layers that cost more than they save: wrappers with one caller, adapters with no second implementation, speculative indirection that was never needed. Inline them.
-
Make adjacent layers change the abstraction. A layer that repeats the same methods and arguments adds reader load without compression. Collapse pass-through layers.
-
Demand interface compression. A broad interface that hides little complexity makes readers learn both the surface and the implementation. Prefer boundaries that hide meaningful decisions.
-
Shrink state scope: prefer pure functions (returns over mutations), locals over fields, fields over module state, and module state over globals. Derive instead of sync.
-
Name the invariant at the boundary, not in every consumer, so the reader learns it once.
-
Before adding a layer or a piece of state, ask: does this reduce reader load somewhere else by at least as much?
-
折叠代价大于收益的层：单调用方包装、没有第二种实现的适配器、从未需要的臆测间接。内联它们。
-
让相邻层改变抽象。 重复同样方法和参数的层增加负担却不压缩。折叠透传层。
-
要求接口压缩。 公开面宽却几乎不藏复杂度，读者得学表面又学实现。优先能藏住有意义决策的边界。
-
缩小状态作用域： 优先纯函数（返回胜过变异）、局部胜过字段、字段胜过模块状态、模块状态胜过全局。推导，别同步。
-
在边界命名不变量， 别在每个消费者里重复，让读者学一次。
-
加层或加状态前问：它在别处至少同等程度地减少了读者负担吗？
The test: Can a new reader answer “where does X come from?” and “what can change X?” in under 30 seconds? If not, cut layers or cut state.
自检： 新读者能否在 30 秒内回答「X 从哪来？」和「什么能改 X？」不能就砍层或砍状态。