Back to Details

principle-minimize-reader-load

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Minimize Reader Load

最小化读者负担

Maintainability is the work a reader must do to understand code. Track two axes:
  1. Layers to trace. How many indirections sit between the question and the answer.
  2. 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.
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.
可维护性是读者为理解代码所必须付出的认知工作。关注两个维度：
  1. 需要追踪的层级。 问题与答案之间存在多少层间接关系。
  2. 需要记住的状态。 读者必须在脑中保留多少隐藏或可变上下文。
原因： 代码被阅读的次数远多于被编写的次数。LOC、圈复杂度和“整洁架构”都只是代理指标。读者负担才是真正重要的东西。这两个维度是相互独立的。一个包含 50 个全局变量的扁平文件，可能和一个包含 6 层适配器堆栈的文件一样难以理解。必须同时控制两者。这是守护上下文窗口的人类类比。读者的工作记忆同样是有限的。
模式：
  • 折叠成本高于收益的层级： 仅有一个调用方的包装器、没有第二种实现的适配器，以及从未被证明必要的推测性间接层。将它们内联。
  • 确保相邻层之间发生抽象变化。 重复相同方法和参数的层会增加读者负担，却无法压缩信息。折叠纯透传层。
  • 要求接口具备压缩能力。 一个没有隐藏多少复杂度的宽泛接口，会迫使读者同时学习其接口表面和底层实现。优先选择能够隐藏重要决策的边界。
  • 缩小状态作用域： 优先使用纯函数（通过返回值而非修改变更状态），其次是局部变量而非字段、字段而非模块状态、模块状态而非全局变量。通过派生而非同步来管理状态。
  • 在边界处说明不变量， 而不是在每个使用方重复说明，让读者只需学习一次。
  • 在添加一个层级或一段状态之前自问：它是否能在其他地方至少同等地降低读者负担？
测试： 一位新读者能否在 30 秒内回答“X 从哪里来？”以及“什么可以改变 X？”如果不能，就削减层级或状态。