★ FEATURED ARTICLE 1. 为什么“代码评审”这件事值得单独拿出来做1.1 从一次真实的评审翻车说起前两年我接手过一个中型项目团队十来个人代码托管在内部 Git 服务上。当时大家约定俗成谁提了合并请求就随手拉一个同事看一眼点个通过就合了。听起来没毛病直到某次上线后出现了一个诡异的空指针排查了整整一个下午最后发现是某次合并请求里一个边界条件被改成了而不是。更离谱的是那次评审记录里明明白白写着“已审阅无问题”。这件事之后我一直在想一个问题代码评审到底是在评审什么是走个流程让领导看到“我们有质量把控”还是真的能在合并之前拦住问题答案显然是后者但现实里绝大多数团队的评审都退化成了前者。原因不复杂——评审太依赖人的自觉和状态了。一个人下午六点被拉去看三百行 diff他能看出什么大概率是扫一眼觉得“差不多”点通过。open-code-review这个标题我第一次看到的时候就觉得它戳中了痛点。它不是一个具体的工具名更像是一类做法的统称把代码评审这件事从“靠人盯”变成“有章法、可复用、能沉淀”的开放流程。所谓“open”我理解有两层意思一是评审过程对团队开放透明谁都能看到评审意见和讨论二是评审的标准和规则是开放的、可迭代的不是某个人脑子里的隐性知识。这篇文章我想聊的就是这套东西。它适合谁看适合那些团队里已经有代码评审动作、但效果一直不理想的开发者适合刚带团队、想建立一套靠谱评审机制的技术负责人也适合一个人写代码、想给自己做“自我评审”的独立开发者。不管你现在用的是哪家代码托管平台下面这些思路都能直接搬过去用。1.2 代码评审真正要解决的三个问题在展开具体做法之前得先把目标想清楚。我见过太多团队把评审做成了“找茬大会”评审者和被评审者对立起来最后大家都不愿意提合并请求。这不是评审的问题是目标定错了。代码评审真正要解决的是三件事。第一是正确性代码逻辑对不对边界条件覆盖了没有异常路径处理了没有。这是最硬核的部分也是最难靠肉眼发现的。第二是可维护性命名是否清晰结构是否合理有没有留下让人半年后看不懂的“天书”。这部分很主观但恰恰是长期成本最高的。第三是知识流动评审过程本身就是一次知识传递评审者了解了这块代码被评审者也从意见里学到了新东西。把这三个目标摆出来你会发现一个残酷的事实纯人工评审在正确性上极其不可靠。人眼对逻辑错误的敏感度远低于对格式错误的敏感度。你让一个人看 diff他第一眼注意到的一定是缩进不对、多了个空行而不是某个条件判断写反了。这不是态度问题是认知负荷的问题。所以open-code-review这套思路的核心就是把机器能做的交给机器把人的精力集中在机器做不了的地方。2. 一套可落地的开放评审流程长什么样2.1 评审前置让机器先过一遍我的做法是在任何人被拉进评审之前先让自动化工具跑一轮。这一轮不涉及人的判断纯粹是机械检查。具体包括几个层面静态检查语法错误、明显的空指针风险、未使用的变量、可疑的类型转换。不同语言有不同工具Python 用ruff或pylintJavaScript 用eslintGo 用go vet加staticcheckJava 用spotbugs。这些工具跑一遍能拦掉大概三成的低级问题。格式化检查代码风格是否统一。这个用prettier、gofmt、black之类的工具直接在提交钩子里做不通过就不让提交。风格问题不应该出现在评审意见里那是对评审者时间的浪费。测试覆盖新增代码有没有对应的测试整体覆盖率有没有下降。这个用 CI 流水线卡住覆盖率掉超过阈值就红灯。安全扫描依赖库有没有已知问题代码里有没有硬编码的密钥。这个用trivy、gitleaks之类的工具扫。这一轮跑完评审者拿到的就是一个“机器已经认可”的版本。他不需要再花时间看格式、看明显的语法问题可以直接进入逻辑和设计的讨论。这一步的收益是巨大的——我实测下来评审者的平均耗时能降一半以上而且评审意见的质量明显提升因为大家不再纠结于鸡毛蒜皮。注意自动化检查的规则不要一次加太多。我见过有团队一上来就开了两百条 lint 规则结果每次提交都是几百个警告大家直接无视了。规则要分批加先加最关键的十几条等团队适应了再逐步收紧。2.2 评审中的角色分工与时间盒机器过完之后进入人工评审。这里有个关键设计评审不是一个人做的事而是有明确分工的。我通常会把评审者分成两类角色。一类是领域评审者他熟悉这块代码的业务背景能判断逻辑是否符合需求、边界条件是否考虑周全。这类评审者通常一到两人是必须到场的。另一类是交叉评审者他可能不熟悉这块业务但从工程角度能看出结构问题、命名问题、可测试性问题。这类评审者一人即可作用是提供“局外人视角”。为什么要设交叉评审者因为领域专家有个盲区——他太熟悉了很多假设在他脑子里是默认成立的反而看不出问题。一个不熟悉的人来问“这里为什么要这么写”往往能逼出真正的设计缺陷。时间盒是另一个关键。我要求每个评审者单次评审不超过三十分钟超过三十分钟的合并请求要么拆小要么安排专门的评审会议。为什么因为人的专注力是有限的超过半小时之后评审质量断崖式下降剩下的时间基本是在“假装看”。与其这样不如把大改动拆成几个小改动每个小改动单独评审。这也是open-code-review里“open”的另一层含义——评审的粒度是开放的、可调整的不是非得一次看完所有东西。2.3 评审意见的写法从“你这里不对”到“我建议这样改”评审意见的写法直接决定了评审氛围。我踩过的坑是早期我写意见很直接比如“这个变量名太烂了改掉”。结果对方很不爽回复“那你来写”。后来我调整了写法改成“这个变量名data有点泛我第一眼没看懂它存的是什么能不能改成userProfileData之类的”效果完全不一样。这里有个原则评审意见要针对代码不要针对人要给出理由不要只给结论要提供选项不要只下命令。具体来说我习惯把意见分成三个等级等级含义处理方式阻塞必须改不改不能合逻辑错误、安全问题、测试缺失建议最好改但不强制命名优化、结构微调、注释补充提问我不确定想了解设计意图、边界假设、未来扩展用等级标注之后被评审者一眼就能看出哪些是必须处理的哪些可以讨论。这比笼统地说“这里有问题”高效得多。而且“提问”这个等级特别有用它把评审从“审判”变成了“对话”很多设计问题就是在这一问一答里暴露出来的。3. 把评审规则沉淀成可复用的资产3.1 评审清单从个人经验到团队标准一个人评审做久了脑子里会形成一套隐性的检查清单。比如我看到一个循环会下意识地想“边界对不对”看到一个函数会想“参数校验了没有”。但这套清单只在我脑子里别人不知道新人更不知道。open-code-review要做的就是把这套隐性清单显性化、文档化。我的做法是维护一份团队共用的评审清单放在代码仓库里和代码一起版本管理。清单按语言和场景分类每条都是可勾选的。比如针对 Python 后端代码清单里会有这么几条所有外部输入是否做了类型和范围校验数据库查询是否有可能返回空结果空结果是否处理了异常捕获是否过于宽泛有没有吞掉不该吞的异常日志里是否打印了敏感信息新增的配置项是否有默认值默认值是否安全这份清单不是一成不变的。每次评审中发现了一个清单里没覆盖的问题就补一条进去。半年下来这份清单就成了团队最宝贵的资产之一。新人入职第一周就是读这份清单读完基本就知道这个团队的代码标准是什么了。提示清单不要写太长超过五十条就没人看了。我的经验是控制在三十条以内按优先级排序最关键的放前面。而且清单要定期清理有些条目随着工具升级已经能自动检查了就从清单里删掉。3.2 评审案例库把踩过的坑变成教材清单是抽象的案例是具体的。我还会维护一个评审案例库把典型的评审讨论记录下来。比如某次评审里有人指出一个并发场景下的竞态条件这个讨论过程本身就很有价值。我会把它整理成一个简短的案例背景是什么、问题是什么、怎么发现的、怎么修的、以后怎么避免。这个案例库的作用有两个。一是培训新人新人看案例比看规则更容易理解。二是复盘每隔一段时间回顾一下看看哪类问题反复出现是不是需要在流程上做调整。比如我们发现“边界条件”类问题出现了七八次那就说明清单里关于边界的条目需要加强或者在自动化测试里增加边界用例的强制要求。案例库不需要写得很正式我用的是最简单的 Markdown 文件一个案例一个文件放在仓库的docs/review-cases/目录下。关键是坚持记录哪怕每次只写三五行。时间长了这就是团队的知识沉淀。3.3 评审指标的度量与反思评审做得好不好不能靠感觉得有数据。我通常会跟踪几个指标评审响应时间从提交合并请求到第一个人开始评审平均多久。这个指标反映团队的响应速度太长说明大家不重视。评审轮次一个合并请求平均要几轮才能通过。轮次太多说明前期沟通不足或者评审标准不清晰。评审意见密度每百行代码有多少条评审意见。太低说明评审走过场太高说明代码质量或评审标准有问题。缺陷逃逸率合并后发现的缺陷里有多少是本该在评审中发现的。这个指标最硬核直接反映评审的有效性。这些指标不需要搞得很复杂用简单的脚本从代码托管平台的 API 里拉数据就行。关键是定期看、定期讨论。我每个月会花半小时看一下这些数据如果发现异常就在团队会上提出来一起分析。比如某个月缺陷逃逸率突然升高一查发现是那个月大家赶进度评审都草草了事。这种问题不靠数据是发现不了的。4. 实操从零搭建一套开放评审流程4.1 第一步确定工具链和自动化边界搭建流程的第一步不是写规则而是确定工具链。我的建议是尽量用代码托管平台自带的功能不要一上来就搞一套复杂的自建系统。主流的代码托管平台都有合并请求、评审意见、自动化检查集成这些基础功能够用了。自动化检查的集成方式我推荐用 CI 流水线。具体来说在仓库里放一个配置文件定义每次提交要跑哪些检查。以常见的 CI 配置为例大致结构是这样的stages: - lint - test - security lint: stage: lint script: - ruff check . - black --check . test: stage: test script: - pytest --covsrc --cov-fail-under80 security: stage: security script: - gitleaks detect --source . - trivy fs --severity HIGH,CRITICAL .这个配置的意思是每次提交先跑 lint再跑测试最后跑安全扫描。任何一步失败整个流水线红灯合并请求就不能合。这样就把机器能做的部分彻底自动化了。注意--cov-fail-under80这个阈值不要设太高。我见过有团队设成 95%结果大家为了凑覆盖率写一堆无意义的测试反而降低了测试的有效性。80% 是个比较平衡的值关键路径覆盖到就行。4.2 第二步配置合并请求模板和评审清单工具链确定之后下一步是配置合并请求模板。这个模板会在每次创建合并请求时自动填充引导提交者填写必要信息。我的模板通常包含这几块## 改动说明 简要描述这次改了什么为什么改 ## 关联需求 关联的需求编号或链接 ## 自测情况 本地跑了哪些测试结果如何 ## 评审清单 - [ ] 外部输入已校验 - [ ] 边界条件已考虑 - [ ] 异常路径已处理 - [ ] 新增代码有测试覆盖 - [ ] 无敏感信息硬编码 - [ ] 文档已同步更新这个模板的作用是把评审前置到提交阶段。提交者在填模板的时候自己就会过一遍清单很多低级问题在这一步就自己发现并修掉了。我实测下来加了模板之后评审意见里关于“测试没写”“边界没考虑”这类问题的比例下降了一半以上。模板里的清单要和前面说的团队评审清单保持一致。清单更新了模板也要同步更新。这个维护成本不高但收益很明显。4.3 第三步约定评审节奏和沟通规范流程和工具都就位之后最后一步是约定人的行为规范。这部分最容易被忽略但恰恰是最关键的。我的做法是定几条简单的规矩第一合并请求不要超过四百行。超过四百行的改动评审质量会急剧下降。如果一次改动确实很大就拆成多个合并请求每个请求聚焦一个子问题。拆分的原则是“每个请求可以独立理解和评审”。第二评审响应时间不超过四小时。工作时间内提交的合并请求四小时内必须有人开始评审。如果没人响应提交者可以直接在群里 相关评审者。这条规矩的目的是避免合并请求堆积堆积越多评审越敷衍。第三评审意见必须当天回复。评审者提了意见提交者当天要回复哪怕是“我看到了明天处理”。这条规矩是为了保持沟通的连续性避免一个合并请求拖好几天。第四有争议就当面聊。如果评审意见来回超过三轮还没达成一致就约个十五分钟的短会当面聊。文字沟通的效率在复杂问题上很低容易产生误解。当面聊往往五分钟就能解决。这几条规矩看起来简单但执行起来需要一点纪律。我的经验是前两周需要有人盯着看到违反规矩的就提醒一下。两周之后大家就习惯了流程就自然运转起来了。4.4 第四步定期回顾和迭代流程跑起来之后不是就完事了。我每个月会做一次简短的回顾看几个问题这个月评审发现了哪些典型问题哪些问题是反复出现的清单和模板需不需要调整自动化检查有没有误报或漏报这个回顾不需要很正式我通常是在团队例会上花十分钟过一下。关键是让流程保持活着而不是变成一纸空文。我见过太多团队流程定完之后就再也没人看过半年后大家该怎样还怎样。流程要迭代要跟着团队的实际问题走才有生命力。5. 常见问题与排查技巧实录5.1 评审意见没人理怎么办这是最常见的问题。合并请求提上去评审者要么不看要么看了不写意见要么写了意见提交者不改。我的排查思路是这样的先看是不是流程太重。如果评审清单有五十条模板要填一大堆评审者一看就头大自然不愿意碰。这时候要简化流程清单砍到十条以内模板只留最关键的几项。再看是不是没有明确责任人。如果合并请求没有指定评审者大家就会觉得“别人会看”结果没人看。解决办法是强制指定评审者而且指定到具体的人不是“后端组”这种模糊的群体。最后看是不是评审没有回报。如果评审做得好没人夸做得差没人管大家自然没动力。解决办法是把评审纳入绩效考核的参考项或者在团队内公开表扬评审质量高的人。这不是搞形式主义而是让好的行为被看见。5.2 评审变成吵架怎么办评审吵架的根源通常是意见针对了人而不是代码。比如“你怎么又写这种代码”这种话一出口就注定要吵。解决办法是在流程里明确一条所有评审意见必须针对代码行不能针对人。评审者在写意见的时候要引用具体的代码行说明具体的问题给出具体的建议。另一个技巧是用提问代替断言。把“这里写错了”改成“这里我不太确定能解释一下为什么这么写吗”很多时候提交者一解释评审者就发现是自己理解错了。即使真的是提交者错了提问的方式也给了他台阶下不会激起对抗情绪。如果已经吵起来了我的做法是立刻叫停文字讨论约当面聊。文字沟通没有语气和表情很容易把中性的话读成攻击性的。当面聊五分钟往往比在评论区吵五十条消息更有效。5.3 评审速度太慢怎么办评审慢通常有两个原因。一是合并请求太大评审者一看就犯怵拖着不想看。二是评审者太忙没有专门的时间做评审。针对第一个原因强制拆分合并请求。我的规矩是超过四百行必须拆拆不了就说明改动本身有问题需要重新设计。拆分之后每个请求可能就几十行评审者五分钟就能看完自然就快了。针对第二个原因给评审留出专门的时间。我试过在团队日历上每天固定留出半小时作为“评审时间”这段时间不安排会议大家就专心看合并请求。效果很好评审响应时间从平均一天降到了两小时以内。5.4 常见问题速查表问题现象可能原因排查方向解决建议评审意见没人理流程太重、责任不清、无回报检查清单长度、评审者指定、激励机制简化流程、强制指定评审者、公开表扬评审变成吵架意见针对人、沟通方式生硬检查评审意见措辞针对代码行、用提问代替断言、当面聊评审速度慢请求太大、评审者太忙检查请求行数、评审时间安排强制拆分、固定评审时间评审走过场没有清单、没有自动化检查清单和 CI 配置建立清单、接入自动化检查缺陷逃逸率高评审标准不清晰、评审者能力不足分析逃逸缺陷类型更新清单、加强培训、增加自动化检查5.5 几个我踩过的坑坑一一开始就追求完美流程。我最早搭流程的时候想一步到位清单写了六十条自动化检查开了上百条规则结果团队怨声载道两周就废了。后来改成先上最核心的十条跑顺了再加反而成功了。流程是长出来的不是设计出来的。坑二把评审当成质量保证的唯一手段。评审能发现很多问题但它不是万能的。有些问题只有测试能发现有些只有线上监控能发现。评审是质量体系的一环不是全部。别把所有希望都压在评审上。坑三忽略评审者的感受。评审者也是人也需要正反馈。我后来加了一个小机制每次评审发现了一个重要问题就在团队群里说一下感谢一下评审者。这个动作很小但效果很好大家评审的积极性明显提高了。坑四清单和模板不同步。有段时间我更新了评审清单但忘了更新合并请求模板结果提交者按旧模板填评审者按新清单看两边对不上。后来我把清单和模板放在同一个文件里维护改一个就自动同步另一个问题就解决了。6. 一个人写代码时怎么用这套东西前面说的都是团队场景但open-code-review这套思路对独立开发者同样有用。一个人写代码没有同事帮你评审但你可以自己给自己做评审。我的做法是写完一个功能之后不马上提交而是隔一天再看一遍。隔一天的好处是你对代码的“作者视角”会淡化更容易用“读者视角”去审视。看的时候对照评审清单一条条过把发现的问题记下来然后统一修改。另一个技巧是用工具模拟评审者。静态检查工具、格式化工具、测试覆盖率工具这些在团队里是给评审者减负的在个人场景下就是你的“虚拟评审者”。把它们配好每次提交前跑一遍能拦掉大部分低级问题。还有一个技巧是写评审日志。每次自己评审发现的问题记在一个文件里。时间长了你会发现自己反复犯某几类错误。比如我发现自己经常忘记处理空列表的情况那就在清单里把这条加粗下次特别注意。这个日志就是你的个人评审资产比任何通用规则都更有针对性。7. 这套流程后续还能怎么扩展流程跑顺之后有几个方向可以继续深化。一个是把评审和需求管理打通每个合并请求都关联到具体的需求评审的时候不仅看代码还看需求是否被完整实现。另一个是把评审和线上监控打通线上出了故障回溯到相关的合并请求看看评审时有没有漏掉什么把教训补进清单。还有一个方向是评审的自动化程度继续提高。现在大语言模型在代码理解上已经有一定能力了可以尝试用它做第一轮评审把明显的问题标出来人工评审只处理模型拿不准的部分。这个方向我还在摸索目前的效果是能拦掉一些低级问题但复杂逻辑还是得靠人。不过这个领域变化很快值得持续关注。最后分享一个我个人的体会评审这件事最大的价值不在于发现了多少问题而在于它逼着你把代码写得更清楚。因为你知道有人会看所以你会把命名写得更准确把结构理得更清晰把注释补得更完整。这种“被看见”的压力本身就是一种质量提升。open-code-review的核心说到底就是让代码评审从“走过场”变成“真对话”让每一次合并都成为一次团队学习的机会。
阅读完成 · 觉得有帮助？
