Google 工程实践：代码评审速度指南——如何在不牺牲代码质量的前提下让评审快起来

文档教程代码评审【免费下载链接】eng-practicesGoogles Engineering Practices documentation项目地址https://gitcode.com/gh_mirrors/eng/eng-practices点击查看免费下载导读本文基于 Google Engineering Practices 仓库中 Speed of Code Reviews 一文系统讲解代码评审Code Review中速度的核心原则评审的响应速度为何关乎整个团队的交付效率、评审响应应多快、如何在专注工作与评审之间取舍以及如何借助带评论的 LGTM、拆分大型 CL、跨时区协作等具体手段把评审流程整体提速。读完本文你将掌握一套可落地的评审节奏管理方法并理解速度与代码健康Code Health之间的正确平衡——快是为了让团队更快地产出而不是为了牺牲质量。本文属于 Google 代码评审指南体系中 The Code Reviewers Guide 的一部分与其配套的 评审标准、评审中该看什么、如何导航一个 CL、如何撰写评审评论 以及 CL 作者指南 共同构成一套完整的评审方法论。文中所有术语CL、LGTM遵循仓库 README 术语表 的定义。术语速记CLchangelist指提交到版本控制或正处于评审中的一个自包含变更其他组织常称之为 change、patch 或 pull-requestLGTM意为 Looks Good to Me是评审者批准一个 CL 时所说的话。一、为什么代码评审必须快团队速度优先于个人速度1.1 优化目标团队的整体产出速度在 Google我们优化的是一支开发团队共同产出产品的速度而不是单个开发者写代码的速度。个人开发速度当然重要但它没有团队整体速度那么重要。这是理解一切评审速度规则的前提评审不是评审者自己的事而是团队协作流水线上的一个环节。一个 CL 被评审拖住受影响的不是作者一个人而是所有依赖该 CL 的后续工作。1.2 慢评审引发的三个连锁后果原文档明确指出当评审变慢时会发生以下三件事整个团队的交付速度下降。没错没有及时响应评审的那个人确实可以去干别的活但是团队其他人的新功能和 Bug 修复会因为这个 CL 等待评审、等待复审而被推迟数天、数周甚至数月。开发者开始抵制评审流程。如果评审者每隔几天才响应一次而且每次响应都要求对 CL 做重大修改这会让开发者非常沮丧并常常表现为抱怨评审者太严格。反过来如果评审者提出的同样是那些确实能改善代码健康的实质性修改但每次作者更新后都能快速响应抱怨往往会消失。大多数关于评审流程的抱怨实际上都是通过让流程变快而解决的。代码健康受到侵蚀。评审慢时团队内部允许提交没那么好的 CL 的压力会增大慢评审还会打消人们做代码清理、重构和对已有 CL 做进一步改进的积极性。其中第二点值得强调严格本身通常不是问题严格但迟缓才是。快节奏下的严格评审既保证了质量又不会积累怨气。1.3 与评审标准的衔接这里需要与 The Standard of Code Review 相互印证评审的首要目的是确保整个代码库的健康状况随时间推移持续改善。因此速度不能以破坏标准为代价——评审者应当批准那些整体上确实改善了系统代码健康的 CL即使它并不完美。速度服务于持续改善而非服务于尽快合入任何东西。慢会阻碍改善CL 被积压、清理和重构被搁置以牺牲标准换来的快同样会损害改善。两条原则必须同时成立。二、评审应该多快一条硬性时间底线2.1 一个工作日是响应上限关于多快原文档给出了两条量化准则如果你当前不在一个需要专注的任务中间那么 CL 送来之后应当尽快评审。响应一个评审请求的最长时间是一个工作日——即最迟在第二天一早给出响应。遵循这两条准则一个典型的 CL 即使需要多轮评审通常也能在同一天内完成多轮往返。这里要再次澄清响应的含义指南关心的不是整个 CL 走完全部评审并被提交的总耗时而是每一轮评审的响应时间。整个流程当然也应该快但单个响应的速度比整个流程的速度更重要——这是下一节的核心论点。2.2 为什么响应快比流程快更重要即便某个 CL 由于规模或复杂度原因走完全程需要较长时间只要评审者在过程中每次都快速响应就能显著缓解开发者对慢评审的挫败感。反过来哪怕总耗时很短但中间出现一次让人干等数天的沉默体验也会很差。因此当你太忙、暂时无法对一个 CL 做完整评审时仍然可以且应该做下面三件事之一发一条简短响应告诉作者你大概什么时候会评审推荐其他可能更快响应的评审者先给出一些初步的宏观评论具体做法见 Navigating a CL in Review 中的先看整体设计、优先发出主要设计意见策略。注意这些都不构成你打断当前编码工作的理由——应当在工作中一个合理的断点break point处再发出这类响应。同时必须强调评审者要花足够的时间做评审确保自己的 LGTM 真的意味着这段代码符合我们的标准标准见 The Standard of Code Review。快速响应不等于敷衍了事理想状态下单个响应既快又经过充分思考。三、速度与中断的权衡不要打断专注工作3.1 唯一的例外个人专注状态指南承认一种个人速度压过团队速度的情形当你正处在一个需要专注的任务中例如正在写代码时不要打断自己去评审。这不是为懒惰开脱而是有充分理由的研究表明开发者被打断后需要很长时间才能重新回到流畅的开发状态。因此在编码中途打断自己去做评审对团队造成的代价大于让另一位开发者多等一会儿评审的代价。3.2 正确做法等待工作断点正确的做法是等到你工作中的自然断点再响应评审请求。断点的例子包括当前编码任务完成时、午饭后、开完会回来时、从茶水间回来时等等。这条规则与一个工作日上限配合使用既不用牺牲自己的专注状态也保证最迟在下一个工作日早晨给出响应。四、跨时区评审让作者当天就能继续当评审双方处于不同时区时需要额外的节奏设计尽量在作者的工作时间结束前把评审意见返回给他让他还有时间当场回应如果作者当天已经下班那就确保你的评审在他第二天开始工作之前完成。跨时区场景的深层痛点在于一次夜间送达的评审会让作者白白损失整整一个工作日。这正是下一节带评论的 LGTM最值得使用的场景之一。五、带评论的 LGTM加速评审的关键技巧5.1 什么是 LGTM With Comments为了加速评审在某些情况下评审者应当给出 LGTM/Approval即使他同时在 CL 上留下了尚未解决的评论。适用条件满足两者之一即可评审者有信心开发者会恰当地处理剩余的所有评论剩余改动是次要的不一定要由开发者在本 CL 中完成。如果这两种意图不明确评审者应当明确指出自己属于哪一种——这能避免作者误解例如把可选建议当成必须修改。这与 How to Write Code Review Comments 中标注评论严重级别如Nit:、Optional:、FYI:的建议一脉相承明确的意图标注让作者能正确排序自己的工作也避免评审往返的浪费。5.2 为什么它特别适合跨时区场景当作者与评审者身处不同时区、作者本来要白白等上一整天才能拿到 LGTM, Approval 时尤其值得考虑 LGTM With Comments——它把等待一天压缩为当天即可继续推进。这一做法也得到 What to Look For In a Code Review 的呼应当 CL 上有多位评审者、你只负责评审其中一部分某些文件、或只评审设计/隐私/安全等特定方面时应在评论中注明你评审了哪些部分并优先给出带评论的 LGTM若你是在确认其他评审者已覆盖其余部分后才给予 LGTM也应显式说明并力求在 CL 达到理想状态后快速响应对应 speed.md#responses 一节。六、大型 CL拆或者至少先给出整体设计意见6.1 首选响应请作者拆分 CL如果有人发来一个大到让你不确定何时才有时间评审的 CL你典型的响应应该是请作者把它拆分成若干个相互叠加的小 CL而不是一次性提交一个必须整体评审的巨型 CL。拆分通常都是可行的而且对评审者帮助极大——即便这需要作者额外付出一些工作量。关于拆分的详细方法论可参见 Small CLsCL 作者指南。那里给出了支持小 CL的完整理由可与本节互为补充评审更快评审者多次抽出 5 分钟评审小 CL远比一次性腾出 30 分钟评审一个大 CL 容易评审更彻底大变更中大量细碎评论来回传递容易让重要问题被遗漏或丢弃更不容易引入 Bug改动越少作者和评审者越容易推理变更影响被拒绝时浪费更少方向错了小 CL 的返工成本远低于大 CL更容易合并与回滚大 CL 长时间开发会产生大量合并冲突且回滚时更容易牵连中间 CL更容易设计好、等待评审时阻塞更少、回滚更简单。需要特别提醒作者也值得评审者知晓评审者有权仅仅因为 CL 太大而直接拒绝它并建议其拆成一系列小变更。同时在 Navigating a CL in Review 中也有对应指引——如果 CL 大到评审者无法判断哪部分是主体可以请开发者指出应优先看什么或请其拆分。关于多大算大Small CLs 给出了一条经验线CL 的理想规模是一个自包含的变更100 行左右通常是合理规模1000 行通常就过大了但跨文件数量同样影响体量——一个文件中 200 行的改动或许可以接受散布在 50 个文件中的 200 行改动通常就太大了。6.2 确实无法拆分时至少先给整体设计意见如果 CL确实无法拆成更小的 CL而你又没有时间快速评审完整个 CL那么至少针对 CL 的整体设计写下一些评论然后把 CL 发回给作者改进作为评审者你的目标之一应该是始终尽快为作者解锁unblock或让其能够采取下一步行动同时不牺牲代码健康。这条先给设计意见、立即发回的策略与 Navigating a CL in Review 高度一致一旦在主体部分发现重大设计问题应立即发出这些评论——哪怕你此刻没有时间评审剩余部分。理由有二开发者常常在发出 CL 后立刻基于它开始新工作重大设计问题不及时发现他们基于错误设计做的后续工作也要返工重大设计改动比小改动耗时更长作者需要尽早开始重做以赶上截止日期。七、长期来看评审会越来越快但永远不要用标准换速度7.1 正向飞轮严格且快速的评审带来长期的提速如果你遵循本指南并且保持评审的严格性你会发现整个评审流程会随着时间的推移越来越快开发者逐渐学会什么才是健康的代码从一开始就送来质量很高的 CL需要的评审时间越来越少评审者学会快速响应不再给评审流程注入不必要的延迟。这是一个互相学习、彼此强化的正向循环——这正是 The Standard of Code Review 中评审的教导功能的体现评审不仅是把关也是让开发者学会写出更少需要返工的代码。7.2 红线不为想象中的提速而妥协标准不要为了想象中速度的提升而妥协代码评审标准或质量——从长远看这种妥协并不会真的让任何事情发生得更快。这与标准文档的原则完全一致完美的代码并不存在只有更好的代码。评审者不应要求作者在批准前打磨每一个细枝末节而应寻求持续改进continuous improvement一个整体上提升了系统可维护性、可读性和可理解性的 CL不应仅仅因为不够完美而被推迟数天或数周。反过来一个明显会恶化代码健康的 CL 绝不应被合入——唯一的例外是紧急情况。八、紧急情况唯一允许全流程快速通过的情形存在少数紧急 CL它们必须以尽可能快的速度走完整个评审流程并且此时质量标准会被放宽。但请务必阅读 Emergencies 中对什么才算紧急情况的界定——远比你想象的要严格。根据 Emergencies 文档紧急 CL 是那种小规模的变更例如让一次重大发布能够继续而不是回滚、修复严重影响线上用户的问题、处理紧迫的法律事务、堵住重大安全漏洞等。在紧急情况下也只有在紧急情况下评审者应该比其他任何事都更关心评审速度和代码正确性它是否真的解决了紧急问题并且这类评审应当优先于其他所有评审。紧急情况解决后还应对这些 CL 再做一次更彻底的复查见 What to Look For In a Code Review。同时必须澄清什么不是紧急情况想在这周而不是下周发布除非有真实的硬性截止日期如合作伙伴协议开发者已经在这个功能上花了很长时间、非常想把它合入评审者都在另一个时区、现在是夜间或者正在外出参加活动周五下班前要是能在开发者走之前合入就好了经理因为软性非硬性截止日期要求当天完成评审并合入回滚一个导致测试失败或构建破坏的 CL。其中硬性截止日期指错过就会发生灾难性后果的日期如合同义务、产品错过发布日期将彻底失败、硬件厂商一年只出货一次等。绝大多数截止日期都是软性的——它们只是希望在某个时间点完成重要但不值得为之牺牲代码健康。如果团队因为发布周期长而反复在周期末尾必须合入只做表面评审的 CL正确的做法是修改流程让大的功能变更尽早进入周期、留出充分的评审时间而不是压榨评审速度。九、给团队落地本文的实践清单综合 Speed of Code Reviews 及配套文档可将上述原则浓缩为一份可执行的清单设定 SLA评审响应最迟一个工作日次日一早不在专注任务中时CL 一到就尽快评审。保护专注写代码时不因评审而中断自己等待自然断点再响应断点包括任务完成、午饭后、会议后等。区分响应速度与流程耗时优先保证每轮响应都快繁忙时至少回复何时评审/推荐评审者/初步宏观评论。为跨时区设计节奏在作者下班前送达意见或在作者次日上班前完成评审善用 LGTM With Comments。熟练使用带评论的 LGTM确信作者会处理剩余评论或剩余改动确属次要时直接给 LGTM 并注明意图。大 CL 先拆后审请作者参考 Small CLs 拆分实在拆不了先发整体设计意见、立即解锁作者。严格但快速快速响应能化解大多数评审太严格的抱怨长期坚持会让 CL 质量与评审速度双向提升。守住标准速度永远不能以牺牲 评审标准 为代价只有符合 紧急情况定义 的 CL 才能全流程破例加速。延伸阅读本仓库还提供与本文直接相关的配套文档建议按需继续深入The Code Reviewers Guide 目录评审者指南的完整章节列表The Standard of Code Review评审的总体标准与原则——批准一个明显改善代码健康的 CL即使它不完美What to Look For In a Code Review评审时该检查的各个方面设计、功能、复杂度、测试、命名、注释、风格、一致性、文档等Navigating a CL in Review多文件 CL 的高效评审顺序先整体、再主体、后其余How to Write Code Review Comments如何写出礼貌、清晰、带严重级别标注的评审评论Handling Pushback in Code Reviews面对作者异议与以后再清理诉求时的处理方式——其中明确提到提高评审速度通常能让关于太严格的抱怨消失与本文第一节相互印证Small CLs面向作者的拆分方法论是解决大型 CL 拖慢评审的根本手段Emergencies紧急 CL 的判定标准与处理流程CL Authors Guide 目录CL 作者视角的完整指南。赞分享文档教程代码评审【免费下载链接】eng-practicesGoogles Engineering Practices documentation项目地址https://gitcode.com/gh_mirrors/eng/eng-practices点击查看免费下载相关推荐Maestro用 YAML 在 5 分钟跑通移动 E2E 自动化测试Maestro用 YAML 在 5 分钟跑通移动 E2E 自动化测试 回归测试跑一轮要等半天最后发现挂掉的不是功能而是一个按钮没找着——这是移动 E2E文档教程代码评审VirtualApp代码质量评审定期进行代码评审VirtualApp代码质量评审定期进行代码评审 代码质量是开源项目长期健康发展的基石尤其对于VirtualApp这样涉及Android沙盒技术的复杂项目。移动开发虚拟化HMCL代码评审指南提升开源项目代码质量的实践HMCL代码评审指南提升开源项目代码质量的实践 为什么代码评审至关重要 在开源项目HMCLhuanghongxun/HMCL的开发过程中代码评审Cod桌面应用游戏开发上一篇HeyGem.ai 无水印输出3 条解锁路径 1 个隐藏参数成片一次到位下一篇StoryDiffusion安全实践内容生成中的伦理审查与风险控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考