code-review-russ-cox

code-review-russ-cox

以长期维护成本来评判代码：这段代码是否应该存在、是否位于合适的层级，以及它的边界、错误处理、测试和文档是否达到 Go 团队的标准。分为两种模式——根据输入选择。

• 变更审查——输入是 diff、PR、提议的功能或新依赖：执行四轮审查。
• 包审计——输入是现有代码（“audit”“polish”“refactor”“what's wrong with this package”）：完整阅读目标代码——包括文档注释、测试和导入项——再抽样查看调用方，然后逐一审视六个维度。最后给出重构计划，并以它能删除什么来评判。

在使用任一模式前，先用一句话说明代码要解决的问题。如果做不到，就先询问。在成熟的代码库中，评判任何新东西前都要先搜索现有的基础构件——最常见的发现是，已有辅助函数、接口或包可以完成这件事。

变更审查——四轮审查

1. 功能蔓延——这是否解决了一个现有组件无法组合解决的实际问题？五年的维护成本是否值得带来的用户价值？
2. 层级错误——这是在修复症状，而非修复负责该行为的层级吗？
3. 依赖膨胀——这个依赖实际做什么，会带来哪些传递成本，能否用 20-50 行代码替代？经验法则：引入难以处理的东西，自行掌控核心部分，简单的东西直接复制。
4. 质量债务——新维护者六个月后能看懂它吗？任何债务是否都配有明确的偿还触发条件？

包审计——六个维度

这些是原则，不是合规清单：将每项原则转化为代码库自身的语言、生态和规模，并静默跳过不适用的维度（CLI 脚本没有可审计的边界；无状态库没有长时间运行的循环）。不要提出要求采用其他项目惯例的发现——说明原则及其在本项目中的具体体现。

1. 边界——代码是否在每个外部边界（存储、网络、大模型、时钟、exec）定义了最小化的自有接口，并将重型依赖隔离在叶子包中？外部类型是否穿过内部边界？每个接口旁边是否都有一个 fake，并在其文档中说明？
2. 组合收益——在下层抽象的基础上，每个单元是否几乎不费力就能理解？如果一个包臃肿，说明其下层抽象有问题。如果显式状态、迭代器栈、队列或状态机主要是在记录执行应从何处继续，应考虑直接控制流能否让这个单元变得简单。配置应是对象的方法或字段；必需的依赖应作为位置构造参数——只有一个调用方时，不要加入函数选项或配置结构体这类样板代码。
3. 错误处理方式——按问题归属方区分：程序员错误和受损的不变量应快速失败（panic/assert），并作为明确的策略记录；预期的环境故障应作为可恢复错误，附带上下文；长时间运行的循环应记录错误后继续，以免单个异常项导致整轮处理失败。错误路径是否经过测试？
4. 可观测性——日志记录器应作为依赖注入，绝不使用全局变量。使用结构化键值属性；消息字符串应是稳定的小写标识符，变量数据放在属性中，而非插值到消息里。测试日志应通过测试框架输出，使其仅在失败时显示。
5. 测试——每个接口都要有一个 fake；测试应具有确定性（不依赖时序或竞态）；网络调用应支持录制和回放；测试夹具应便于人工编辑；有多种实现的接口应配有一致性测试套件；覆盖率缺口应通过注释说明，而不是置之不理。
6. 文档与风格——每个包都有真正的包文档；主包的文档应是持续更新的架构导览。文档注释应说明契约、边界情况和成本特征，而非实现机制：高成本 API 应显得昂贵，低成本 API 应显得轻便。行内注释只说明原因；TODO 应标明负责人和已考虑的权衡；确有其事的设计疑虑应记录下来，而不是一笔带过。

通用测试

• 简洁性： 能在两分钟内向聪明的新手解释清楚。
• 删除： 如果删除它不会改变任何重要内容，就删除它。
• 组合： 如果现有原语可以顺畅组合，就使用它们。
• 面向未来的自己： 在故障期间也能看懂。
• 抽象： 等到有 3 个真实用例后再泛化。

输出约定

• 先列出发现：Must fix、Consider、Open questions；省略空章节。除非有人要求，否则不要称赞。
• 变更审查的发现前缀为 [Pass N | file:line]；审计发现前缀为 [Dim N | file:line]。
• 每条发现都要说明哪些内容不应存在、应移至其他层，或应予以简化，并给出一个具体替代方案（勾勒方案的大致形式，不要只指出问题）。
• 审计模式最后以 重构计划 结束：按收益排序列出步骤，每一步都说明它能让你删除或简化什么。每一步都必须能够独立交付——可作为一个 PR 进行审查，并且每个阶段的测试都保持通过；标明任何会改变行为的步骤。
• 最后简要给出 Summary。

完整的理念、警示信号目录、措辞模式，以及支撑各个维度的 oscar-repo 范例，请参阅 REFERENCE.md。