Google 代码审查标准eng-practices以代码健康为最高准则的批准决策指南【免费下载链接】eng-practicesGoogles 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 还澄清了两个贯穿全文档的术语CLChangelist变更列表指一个自包含的、已提交到版本控制或正在接受审查的改动。其他组织常称之为 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可以选择忽略。这套做法与 如何编写代码审查评论 中更完整的严重程度标注体系一脉相承标签含义Nit:小问题。技术上应该做但影响不大属于打磨级别Optional或 Consider:可能是个好主意但不是硬性要求FYI:不要求在本 CL 中处理仅供未来参考没有这些标签时作者很容易把每一条评论都当作必修项而明确标注严重程度能让审查意图显性化帮助作者排定优先级避免误解。紧急情况是唯一的例外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-practicesGoogles Engineering Practices documentation项目地址: https://gitcode.com/gh_mirrors/eng/eng-practices创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Google 代码审查标准（eng-practices）：以代码健康为最高准则的批准决策指南
Google 代码审查标准eng-practices以代码健康为最高准则的批准决策指南【免费下载链接】eng-practicesGoogles 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 还澄清了两个贯穿全文档的术语CLChangelist变更列表指一个自包含的、已提交到版本控制或正在接受审查的改动。其他组织常称之为 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可以选择忽略。这套做法与 如何编写代码审查评论 中更完整的严重程度标注体系一脉相承标签含义Nit:小问题。技术上应该做但影响不大属于打磨级别Optional或 Consider:可能是个好主意但不是硬性要求FYI:不要求在本 CL 中处理仅供未来参考没有这些标签时作者很容易把每一条评论都当作必修项而明确标注严重程度能让审查意图显性化帮助作者排定优先级避免误解。紧急情况是唯一的例外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-practicesGoogles Engineering Practices documentation项目地址: https://gitcode.com/gh_mirrors/eng/eng-practices创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考