代码评审规范：让评审成为知识传递的杠杆

代码评审是研发流程中最容易被形式化的一环。它常常退化成两种极端：要么是“看一遍就通过”，评审变成走流程；要么是“逐行挑刺”，作者和评审者都疲惫不堪。真正有效的代码评审，目标不是证明谁更聪明，而是让变更在合入前获得一次结构化的集体判断，同时把隐性知识从个人经验变成团队共识。它既是质量关口，也是学习机制，还是一种低成本的架构对齐方式。如果只把评审当作找 Bug，就会浪费它最大的价值。

评审到底在评审什么

很多团队对评审的期待不清晰，导致评论五花八门。有人关注命名，有人关注性能，有人关注格式，有人只点赞。评审目标需要提前对齐，通常可以分成四类。

这四类目标有优先级。正确性和可维护性通常高于风格问题；一致性可以通过自动化解决；知识传递则依赖评论质量和沟通方式。评审者不必在一次评审中覆盖所有维度，但团队需要知道这次评审最关心什么。

控制 PR 规模：评审质量的第一杠杆

代码评审最大的敌人不是技术难度，而是规模。一个 2000 行的 PR，没人能认真看完；一个 50 行的 PR，评审者能给出具体、深入的意见。研究表明，超过 400 行的变更，缺陷发现率明显下降。控制 PR 规模，比任何评审技巧都更有效。

一些可操作的规则：

• 单个 PR 尽量控制在 200 到 400 行以内，超过则拆分。

• 按逻辑拆分，而不是按文件拆分。一个 PR 解决一件事。

• 重构与功能变更分开提交，避免混在一起。

• 大功能可以拆成多个小 PR，逐步合入，而不是一次合并。

• 如果必须大 PR，提前说明结构，并标注重点评审区域。

• 使用草稿 PR 提前收集方向性意见，而不是写完再评审。

拆分 PR 不是额外工作，而是把评审成本前移。小 PR 更容易回滚，更容易定位问题，也更容易让新人参与。

评论分级：让作者知道什么必须改

评审评论如果没有优先级，作者会陷入困惑：哪些必须改，哪些可以讨论，哪些只是建议。团队可以约定一套评论前缀，让沟通更高效。

这套前缀不需要复杂工具，写在评论开头即可。它的价值是降低情绪冲突：nit 不会让作者觉得被否定，blocker 也让作者知道优先级。评审者应避免用模糊的“这里不太好”，而应说明原因、给出替代方案，或至少指出问题类型。

自动化能做的，不要留给人

人工评审的注意力是稀缺资源，应该用在自动化无法判断的地方。格式、静态检查、类型错误、单元测试、依赖漏洞、覆盖率下降，这些都应该由 CI 自动完成。评审者不需要在评论里指出缩进或分号。

自动化不是替代评审，而是把评审者从机械问题中解放出来。团队应该定期回顾：哪些评论反复出现？如果某个问题出现三次以上，就应该考虑加入自动化规则或文档。

评审节奏与响应时间

评审如果拖太久，作者会切换上下文，PR 会积累冲突，团队会失去动力。评审节奏需要约定，而不是靠自觉。

• 提交 PR 后，作者应主动说明背景、变更范围、测试方式和风险点。

• 评审者应在约定时间内响应，例如 4 小时或 1 个工作日内。

• 如果无法及时评审，应告知作者或转交他人。

• 作者不应在未评审的情况下持续追加大量提交。

• 评审通过后，作者负责合入并确认 CI 通过。

• 紧急修复可以简化流程，但事后需要补评审。

评审不是审批，而是协作。响应时间的目标不是形式主义，而是保持变更流动，减少长期分支和合并冲突。

评审者该说什么，不该说什么

评审评论的质量，直接影响团队氛围。好的评论具体、尊重、可执行；差的评论模糊、情绪化、针对个人。

应该说的：

• “这个循环在数据为空时会返回 undefined，建议在进入循环前加保护。”

• “这个函数同时处理了格式化和校验，是否拆成两个函数更清晰？”

• “这里和 UserService 中的逻辑重复，是否可以抽到公共模块？”

• “这个命名容易和 getUser 混淆，建议改为 fetchUserProfile。”

不该说的：

• “这写得不对。”

• “你怎么又这样写？”

• “这不是最佳实践。”

• “随便你吧。”

评审者应针对代码，不针对人。如果情绪激动，可以先写草稿，过十分钟再发。作者也应把评论视为对代码的反馈，而不是对能力的否定。

度量：评审健康度看什么

评审需要度量，但不能用评论数量或评审时长简单考核。更好的指标是看流程是否健康。

如果 PR 规模持续偏大，说明拆分没做好；如果响应时间很长，说明评审责任不清晰；如果评论密度极高但缺陷逃逸也高，说明评论集中在风格而非关键逻辑。度量应结合回顾，而不是用来排名。

常见反模式

代码评审中有一些反复出现的反模式，识别它们可以避免流程退化。

• 橡皮图章：只点赞不评论，评审失去意义。

• 个人风格之争：把偏好当规范，反复争论空格和命名。

• 无限循环：同一 PR 反复修改，始终无法合入。

• 评审者垄断：只有一两个人能评审，形成瓶颈。

• 作者防御：把评论当攻击，拒绝讨论。

• 隐藏上下文：PR 描述为空，评审者只能猜。

• 大 PR 突击：一次提交几千行，要求当天评审。

• 只盯细节：忽略架构、边界和测试，只改格式。

这些反模式通常不是人的问题，而是流程和规范缺失。团队应在回顾中讨论，并逐步修正。

落地检查清单

• PR 是否控制在小规模，是否一件事一个 PR？

• PR 描述是否说明背景、范围、测试和风险？

• 评论是否使用分级前缀，作者是否知道优先级？

• 自动化是否覆盖格式、静态检查、类型和测试？

• 评审者是否在约定时间内响应？

• 评论是否具体、尊重、可执行？

• 是否避免个人风格之争，规范是否写入文档？

• 是否有关键路径的测试覆盖要求？

• 是否定期回顾评审数据，而非用它考核个人？

• 新成员是否参与评审，是否有人带教？

• 紧急流程是否有事后补评审机制？

• 评审是否覆盖安全、权限和隐私风险？

代码评审不是研发流程的负担，而是团队工程能力的基础设施。它把个人经验变成集体知识，把潜在风险提前暴露，把规范从文档变成日常实践。评审做得好，团队会越来越敢改代码，因为知道变更会被认真对待；评审做得差，团队会越来越怕改代码，因为每次提交都像一场审判。规范的目的，不是增加流程，而是让协作变得可预期、可学习、可持续。当评审从挑错转向知识传递，它就不再是关卡，而是杠杆。