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 do not earn their keep: wrappers with one caller, adapters with no second implementation, indirection introduced for a future that never came. Inline them.
  • 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、cyclomatic complexity和"整洁架构"都是间接指标，而读者负担才是核心关键。这两个维度是相互独立的。一个包含50个全局变量的扁平文件，可能和一个6层的适配器栈一样难以推理。要同时防范这两种情况。这类似于守护上下文窗口的人类版本：读者的工作记忆也是有限的。
模式：
  • 合并无价值的层级：仅被单次调用的包装器、没有第二种实现的适配器、为从未到来的未来而引入的间接调用，这些都应被合并，直接内联。
  • 缩小状态作用域：优先选择纯函数（用返回值而非修改），局部变量优先于字段，字段优先于模块状态，模块状态优先于全局变量。优先推导而非同步。
  • 在边界处定义不变量，而非在每个消费者中定义，这样读者只需学习一次。
  • 在添加层级或状态之前，问自己：这是否能在其他地方减少至少同等程度的读者负担？
测试标准：新读者能否在30秒内回答“X来自哪里？”和“什么能改变X？”？如果不能，就削减层级或状态。