Google 代码审查标准（eng-practices）：以代码健康为最高准则的批准决策指南

Google 代码审查标准（eng-practices）：以代码健康为最高准则的批准决策指南

【免费下载链接】eng-practicesGoogle's Engineering Practices documentation项目地址: https://gitcode.com/gh_mirrors/eng/eng-practices

本文源自本仓库 The Standard of Code Review 文档，是 Google 代码审查指南（审查者指南 与 CL 作者指南）中统领全局的纲领性章节。它回答了一个所有审查者都会遇到的根本问题：什么样的 CL 值得批准（LGTM），什么样的 CL 必须打回。读完本文，你将掌握 Google 多年工程实践沉淀出的审查基准——在"推动开发者前进"与"守护代码库健康"之间做权衡的完整决策框架，以及处理审查分歧时的升级路径。

引言：代码审查的首要目的

代码审查（Code Review）是"由代码作者之外的其他人检查这段代码"的过程（见 审查总览）。而在 Google 的工程实践中，代码审查有一个明确的、压倒一切的首要目的：

确保 Google 代码库的整体代码健康（code health）随着时间推移不断改善。

所有代码审查的工具与流程设计，都服务于这一终点。理解这一点是理解其余一切规则的前提——standard.md中的每一条原则、每一个例外，最终都是为了回答"这个 CL 是否让代码库变得更好"。

本仓库 README 还澄清了两个贯穿全文档的术语：

• CL：Changelist（变更列表），指一个自包含的、已提交到版本控制或正在接受审查的改动。其他组织常称之为 change、patch 或 pull-request。
• LGTM：即 "Looks Good to Me"，审查者批准一个 CL 时所说的话。

必须平衡的权衡：前进的进度 vs. 代码健康

要实现"代码健康持续改善"这个目的，审查者必须面对一组相互冲突的权衡（trade-offs）：

一方面，开发者必须能够"取得进展"（make progress）。如果一个改进永远无法合入代码库，那么代码库就永远不会变好；如果审查者让任何改动都极难通过，开发者就会失去未来继续改进的积极性。审查流程不该成为改进的阻力。

另一方面，审查者有责任确保每个 CL 的质量足够高，使代码库的整体健康不随时间推移而退化。这之所以棘手，是因为代码库的退化往往不是一次性的灾难，而是通过一次次微小的健康度下降累积而成——尤其当团队面临巨大时间压力、不得不走捷径去达成目标时，这种"温水煮青蛙"式的退化最为常见。

此外，审查者对自己审查的代码拥有所有权与责任感（ownership and responsibility）：他们要确保代码库保持一致（consistent）、可维护（maintainable），以及 在代码审查中应该看什么 中提到的其他所有要求。

核心准则：批准"确定在改善代码健康"的 CL，即使它不完美

在上述权衡之上，standard.md给出了全部代码审查准则中最具纲领性的那条规则：

一般来说，只要一个 CL 处于"它确实在改善整个系统的代码健康"的状态，审查者就应该倾向于批准它——即使这个 CL 并不完美。

这是所有代码审查指南中的"最高原则"（the senior principle）。它的含义需要仔细拆解：

• 标准是"改善"，不是"完美"：CL 只要整体上让代码库变得更好，就值得合入。
• 审查者的否决权依然存在：如果某个 CL 增加了一个审查者根本不想放进系统的功能，那么即使代码写得再好，审查者也可以拒绝批准。标准不剥夺审查者的方向判断权，它针对的是"质量是否完美"层面的误用。
• 没有"完美代码"，只有"更好的代码"：审查者不应要求作者在批准前打磨 CL 的每一个细枝末节，而应权衡"推动前进的需要"与"所提建议的重要性"。

standard.md明确呼吁审查者追求的是持续改进（continuous improvement），而非完美主义：一个整体上改善了系统可维护性、可读性、可理解性的 CL，不应该仅仅因为它"不完美"就被拖延数天甚至数周。

"Nit: " 前缀：区分必修项与可选的打磨点

为了让"持续改进"落地为可操作的行为，文档给出了一条具体的沟通约定：

审查者永远可以自由地留下"这里还能更好"的评论；但如果它并不重要，就用类似"Nit: "的前缀开头，让作者知道这只是一个可以选择的打磨点（a point of polish），可以选择忽略。

这套做法与 如何编写代码审查评论 中更完整的严重程度标注体系一脉相承：

没有这些标签时，作者很容易把每一条评论都当作必修项；而明确标注严重程度能让审查意图显性化，帮助作者排定优先级，避免误解。

紧急情况是唯一的例外

standard.md特别加了一条注释，堵死任何借口的滥用：

本文档没有任何内容为"合入一个确定会恶化系统整体代码健康的 CL"辩护。唯一允许这么做的时机是紧急情况。

也就是说，"持续改进"的底线是不可突破的：CL 可以不够完美，但绝不能明确地让系统变得更糟。唯一的例外是紧急情况（emergency），而 紧急情况 对此有非常严格的界定——它必须是小型改动，且属于以下类型之一：让重大发布可以继续而非回滚、修复严重影响线上用户的生产缺陷、处理紧迫的法律问题、堵上重大安全漏洞等。

反过来，紧急情况文档 明确列出了什么不是紧急情况：想这周而非下周发布（除非存在硬性合同截止日期）、开发者花了很长时间做这个功能很想合入、审查者在不同时区或休假中、周五下班前想收工、管理者因软性截止日期要求当天合入、回滚导致测试失败的 CL……这些都不构成降低审查标准的理由。文档还警告：如果团队反复在发布周期末尾"必须合入"而只做表面审查，这是项目堆积技术债的常见路径；正确的做法是调整流程，让大的功能改动尽早进入周期。

Mentoring：审查的教育职能

代码审查还有一个重要职能——教学：让开发者学到关于一门语言、一个框架或通用软件设计原则的新东西。standard.md明确肯定：分享知识本身就是随时间改善系统代码健康的一部分，因此随时可以留下帮助开发者学习的评论。

但要记住纪律：如果评论纯粹是教育性的，而对达到本文档所述标准并非关键，请用 "Nit: " 前缀或其他方式表明它在当前 CL 中不是必须解决的。这一点与 审查者指南 中的"好事原则"呼应——审查者应该表扬开发者做得好的地方，告诉开发者"做对了什么"在教学价值上往往比指出错误更有意义。

四项核心原则

standard.md的 Principles 一节给出了裁决冲突时优先级最高的一组原则，共四条：

1. 技术事实与数据优先于意见和个人偏好。当审查中的分歧涉及可验证的事实（性能、正确性、行为差异）时，用数据和事实说话，而不是用"我觉得"。

2. 风格问题上，风格指南 是绝对权威。任何不在风格指南中的纯风格点（如空白符）都只是个人偏好。风格应与代码库中已有的保持一致；如果之前没有既定风格，就接受作者的风格。注意：这条原则不能阻止审查者提出风格改进建议——looking-for.md 允许审查者用 "Nit:" 前缀提出风格指南之外的改进点，但不能仅凭个人风格偏好阻塞 CL 提交。同时，作者不应把大规模风格改动与功能改动混在同一个 CL 里（这会让 diff 难以阅读、合并与回滚变复杂），例如"重排整个文件格式"应单独成一个 CL。

3. 软件设计问题几乎从来不是纯粹的风格或个人偏好问题。设计建立在底层原则之上，应当依据原则权衡，而不是凭个人口味。有时确实存在多个同样有效的选项——如果作者能（通过数据或扎实的工程原则）证明多种方案同等有效，那么审查者应该接受作者的选择；否则，就由标准软件设计原则来决定。

4. 如果没有其他规则适用，审查者可以要求作者与当前代码库保持一致——前提是这样做不会恶化系统的整体代码健康。

这四条原则的优先级顺序实际上构成了一个裁决漏斗：先看事实与数据 → 再看风格指南 → 再看软件设计原则 → 最后兜底看与现有代码的一致性。关于"现有代码与风格指南不一致时怎么办"，looking-for.md 给出了补充裁决：风格指南是绝对权威，指南要求的必须遵守；指南只是建议时，则在新代码与周围代码之间做判断，倾向于遵循风格指南（除非局部不一致会过于混乱），并且鼓励作者为清理旧代码提交 bug 并加 TODO。

解决冲突：从共识到升级的完整路径

审查中分歧不可避免，Resolving Conflicts 给出了一个明确的升级阶梯：

第一步：达成共识。任何审查冲突中，第一步永远是开发者和审查者基于本文档以及 CL 作者指南 和本 审查者指南 中的其他文档，尝试达成共识。也就是说，争论的仲裁依据是这套已写明的准则，而不是个人权威。

第二步：面对面沟通。当共识特别难以达成时，安排一次面对面会议或视频会议往往比在评论里来回争论更有效。（如果这样做，务必把讨论结果作为一条评论记录在 CL 上，供未来的读者参考——沟通结论必须留痕。）

第三步：升级（escalate）。最常见的升级路径包括：更广泛的团队讨论、请技术负责人（Technical Lead）介入、询问代码维护者（maintainer）的裁决、或请工程经理（Eng Manager）协助。

文档给出一条红线般的忠告：不要让 CL 因为作者和审查者无法达成一致而干晾着。这条忠告与 处理审查中的异议 形成了完整闭环——那边处理的是"作者对建议的异议"，这边处理的是"双方僵持不下的结构性冲突"。

标准的落地：在整套指南中的位置

standard.md是审查者指南的"总纲"，它定义的是目标与基准；而它的姊妹文档定义了达成该基准的具体操作：

• 在代码审查中应该看什么：从设计、功能、复杂度、测试、命名、注释、风格、一致性、文档、逐行审查、上下文、肯定优点等十二个维度展开审查清单，其"整体设计"检查正是standard.md"代码健康"基准的具体化。
• 导航一个待审查的 CL：给出了高效浏览多文件 CL 的三步法——先看 CL 描述与整体意图、先看改动最重要的部分、再按合理顺序看完其余部分；其中"整体设计有问题就先发评论"的做法，正是为了避免在注定要重写的代码上浪费时间。
• 代码审查的速度：一个工作日内响应、把 LGTM with Comments 作为加速手段等，都服务于"持续改进"这一目标——审查太慢本身就是代码健康的敌人。
• 如何编写代码审查评论：礼貌、解释原因、平衡指导与放手、标注严重程度，让标准能以不伤害协作的方式落地。
• 处理审查中的异议：当作者对建议提出异议时，先判断谁是对的；坚持"现在就清理，不要留到以后"——"以后再说"是代码库退化的常见途径，这与standard.md"不恶化代码健康"的底线完全一致。
• 对应地，CL 作者指南（含 编写良好的 CL 描述、小 CL、如何处理审查者评论）则从作者侧配合这套标准的执行。

结语：把"持续改进"作为审查的北极星

把standard.md的全部内容压缩成一句话，就是：审查者应该批准那些"确定让系统变得更好"的改动，哪怕它们不完美；同时永远不要批准让系统变差的改动，除非那是真正的紧急情况。

这套标准之所以被称为"最高原则"，是因为它承认了工程现实的两面性：完美主义会扼杀改进的意愿，放任自流会侵蚀代码库的健康。真正的审查艺术在于时刻权衡——用技术事实和风格指南裁决分歧，用 "Nit:" 区分轻重，用升级机制化解僵局，用 Mentoring 放大每一次审查的教育价值，最终让团队以越来越快的速度，持续产出越来越健康的代码。

【免费下载链接】eng-practicesGoogle's Engineering Practices documentation项目地址: https://gitcode.com/gh_mirrors/eng/eng-practices