Back to Details

code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code

代码

Objective

目标

Treat code as an executable specification of current behavior, not a record of the bugs, workarounds, and shifting assumptions that produced it.
Implement what is required with the fewest necessary concepts. Complexity should grow only when required behavior or constraints grow. Fewer lines are not the goal; clear invariants, ownership, control flow, and verifiability are.
将代码视为当前行为的可执行规范，而不是对其形成过程中那些缺陷、变通做法和不断变化的假设的记录。
以尽可能少的必要概念实现所需行为。复杂度只应在所需行为或约束增加时增长。目标不是减少代码行数；而是让不变量、所有权、控制流和可验证性保持清晰。

Core principle

核心原则

Bugs, examples, and change requests are evidence about the design, not automatic reasons to add another branch, helper, layer, or option.
text
observed failure → intended invariant → implementation at the owning boundary
not:
text
observed failure → permanent special case
A failing example shows what happened. It may not reveal the correct rule, its owner, or its boundary, so establish those before choosing a fix.
When several implementations satisfy the requirements, prefer, in order:
  1. Correcting the existing responsibility or abstraction.
  2. Consolidating related logic around a shared invariant.
  3. Replacing special cases with a rule that represents the domain.
  4. Adding a branch or abstraction only for genuinely distinct behavior.
缺陷、示例和变更请求是关于设计的证据，而不是自动添加另一个分支、辅助函数、层或选项的理由。
text
observed failure → intended invariant → implementation at the owning boundary
而不是：
text
observed failure → permanent special case
失败的示例只能表明发生了什么，未必能揭示正确规则、规则的归属方或其边界，因此应先确定这些内容，再选择修复方式。
当有多种实现都满足要求时，按以下顺序优先选择：
  1. 修正现有职责或抽象。
  2. 围绕共享不变量整合相关逻辑。
  3. 用表示领域规则的逻辑替换特殊情况。
  4. 仅当行为确实不同时，才添加分支或抽象。

Example

示例

Intended behavior: archived accounts cannot start new jobs. Observed failure: one archived account started a job through the retry endpoint.
A patch keyed to the incident encodes the instance, not the rule:
ts
if (account.id === "reported-account") {
  throw new Error("Account cannot start jobs");
}
Enforcing account eligibility at the shared job-start boundary, used by both initial and retried requests, states the rule once and covers every route that starts a job.
预期行为：已归档账户不能启动新任务。观察到的失败：一个已归档账户通过重试端点启动了任务。
以该事件为键的补丁编码的是具体实例，而不是规则：
ts
if (account.id === "reported-account") {
  throw new Error("Account cannot start jobs");
}
在初始请求和重试请求共同使用的共享任务启动边界上执行账户资格校验，可以只表达一次该规则，并覆盖所有启动任务的路由。

Workflow

工作流程

  1. Establish the contract. Identify inputs, outputs, side effects, failure behavior, compatibility, performance, and security constraints. For a refactor, separate observable behavior that must stay stable from details that may change.
  2. Understand the current design. Trace the relevant code paths, data flow, tests, and conventions. Find where the responsibility and its invariant already live before creating a new home for them.
  3. Find accidental complexity. Look for duplicated decisions, scattered invariants, historical branches, needless indirection, premature generalization, conflicting sources of truth, and stored state that could be derived.
  4. Implement the governing rule. Put behavior at the boundary that owns it. Prefer a direct change when the problem is local. Keep scope to the requested behavior; a nearby fix is not permission for unrelated cleanup or architectural expansion.
  5. Simplify the result. Remove code the change made redundant, so the implementation can be understood without reconstructing its edit history.
  6. Verify. Use the strongest practical evidence: focused tests, type checks, linting, builds, or direct execution. Test the invariant and its meaningful boundaries, not only the reported example, and confirm unrelated behavior and public contracts still hold.
  1. 确定契约。 识别输入、输出、副作用、失败行为、兼容性、性能和安全约束。对于重构，应将必须保持稳定的可观察行为与可以更改的细节区分开来。
  2. 了解当前设计。 追踪相关代码路径、数据流、测试和约定。在为职责及其不变量创建新的归属位置之前，先找出它们目前位于何处。
  3. 发现偶然复杂性。 查找重复决策、分散的不变量、历史遗留分支、不必要的间接层、过早泛化、相互冲突的事实来源，以及本可推导出来的存储状态。
  4. 实现通用规则。 将行为放在拥有该行为的边界上。问题局部化时，优先直接修改。将范围限定在请求的行为内；修复附近问题并不代表可以顺带进行无关清理或扩展架构。
  5. 简化结果。 删除因本次变更而变得冗余的代码，使实现无需还原编辑历史也能被理解。
  6. 验证。 采用最有力且切实可行的证据：聚焦测试、类型检查、linting、构建或直接执行。测试不变量及其有意义的边界，而不只是报告中的示例，并确认无关行为和公共契约仍然成立。

Design rules

设计规则

  • Domain over incidents: Model the category that determines behavior instead of listing known cases. Keep explicit cases when the domain genuinely defines separate behaviors.
  • One source of truth: Own each invariant and piece of state in one place. Derive secondary values rather than synchronizing copies.
  • Local clarity over speculative reuse: Small duplication can be cheaper than the wrong abstraction. Generalize once the shared concept is stable enough to name.
  • Rewriting over layering: When a responsibility changes, update its existing expression. Avoid wrappers, compatibility branches, and parallel paths unless a real compatibility requirement exists.
  • Semantic over syntactic compression: Remove concepts that add neither behavior nor clarity. Keep structure that makes constraints, ownership, and failure modes explicit.
  • Convergence over accumulation: Repeated work in one area should reinforce a coherent model. If each defect adds another exception, flag, wrapper, or source of truth, revisit the governing abstraction instead of extending the patchwork.
  • 领域优先于事件： 建模决定行为的类别，而不是罗列已知案例。当领域确实定义了彼此不同的行为时，保留显式情况。
  • 单一事实来源： 让每个不变量和每份状态都由唯一位置负责。派生次要值，而不是同步副本。
  • 局部清晰优先于推测性复用： 与其使用错误的抽象，少量重复有时成本更低。只有当共享概念已经稳定到可以准确命名时，才进行泛化。
  • 重写优先于分层叠加： 当职责发生变化时，更新其现有表达。除非存在真实的兼容性需求，否则避免使用包装器、兼容性分支和并行路径。
  • 语义优先于语法压缩： 删除既不增加行为也不提升清晰度的概念。保留能够显式呈现约束、所有权和失败模式的结构。
  • 收敛优先于累积： 同一领域的重复工作应强化一个连贯模型。如果每次修复缺陷都会新增另一个例外、标志、包装器或事实来源，就应重新审视承载该规则的抽象，而不是继续扩展拼凑式补丁。

Complexity gate

复杂度门禁

Before adding a branch, abstraction, dependency, configuration option, or state field, ask:
  1. What distinct behavior or constraint requires it?
  2. Is the same rule already represented elsewhere?
  3. Could an existing responsibility express it more clearly?
  4. Does it model the domain or memorialize one example?
  5. Would removing it change required behavior or hide an important invariant?
Reject complexity that does not add required behavior, preserve a real contract, or make an important invariant clearer.
在添加分支、抽象、依赖项、配置选项或状态字段之前，先问：
  1. 有哪种独特行为或约束要求引入它？
  2. 同一规则是否已在别处体现？
  3. 现有职责能否更清晰地表达它？
  4. 它是在建模领域，还是在固化某个示例？
  5. 移除它是否会改变所需行为或掩盖重要不变量？
拒绝那些既不增加所需行为、不维护真实契约，也不让重要不变量更清晰的复杂性。

Success criteria

成功标准

The change implements the intended behavior, preserves required contracts, handles the broader class the example represents, keeps ownership and invariants clear, fits the surrounding system, and is verified in proportion to its risk. The design is at least as coherent as before.
Guiding maxim: Code should express what the system does, not how it got there.
变更实现了预期行为，保留了必要契约，处理了示例所代表的更广泛类别，确保所有权和不变量清晰，与周边系统契合，并使验证力度与风险水平相称。设计的连贯性至少不应低于变更前。
指导准则： 代码应表达系统做什么，而不是它是如何走到今天的。