如何优雅地处理评审意见：Google Engineering Practices 中 CL 作者的代码评审沟通指南

如何优雅地处理评审意见：Google Engineering Practices 中 CL 作者的代码评审沟通指南

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

当你的 CL（changelist，即一次自包含的代码变更，其他团队也称之为 change、patch 或 pull-request，术语见 README.md）提交给评审人（reviewer）后，几乎一定会收到若干条评审意见。如何处理这些意见，直接决定了你的代码能否顺利合入、评审体验是否愉快，以及代码库的整体健康度。本文基于 Google Engineering Practices 文档中的 handling-comments.md 展开，从心态调整、代码修复、协作式沟通到冲突升级，给出 CL 作者在评审各阶段可立即落地的完整行动指南，帮助你更快通过评审并获得更高质量的评审结果。

本指南属于 The CL Author's Guide 三篇系列文档之一（另两篇是 Writing Good CL Descriptions 与 Small CLs），同时与评审人一侧的 How to Write Code Review Comments、The Standard of Code Review 互为镜像，建议对照阅读。

不要把它当成针对你个人的攻击

评审的目标是维护代码库和产品的质量。当评审人对你的代码提出批评时，请把它视为评审人试图帮助你、帮助代码库的行为，而不是对你个人或你能力的攻击。

即使是最优秀的工程师，也偶尔会遇到情绪化的评审意见。文档明确指出：评审人在评论中流露沮丧情绪并非良好实践，但作为开发者，你应当对此有所准备。遇到这类评论时，先问自己一个问题：

“评审人真正想传达给我的、有建设性的内容是什么？”

然后按照这个建设性意图去理解和行动，忽略语气上的不友善。

永远不要在愤怒中回复评审意见

这是文档强调的职业底线：永远不要在愤怒中回复代码评审评论。在愤怒状态下回复，是对职业礼仪的严重破坏，而且这段对话会永久保存在代码评审工具的历史记录里，被后续所有人看到。如果你过于愤怒或烦躁、无法友善地回复，正确做法是：

1. 暂时离开电脑一段时间；
2. 或者先去做别的事情；
3. 等到情绪平复到足以礼貌回复时再回来。

评审人不友善时的处理路径

如果评审人提供的反馈总体上不具建设性、不够礼貌，文档给出的处理路径是分级的：

1. 当面沟通：当面（或视频通话）向评审人解释你不喜欢什么、希望对方怎样改变；
2. 私下邮件：无法当面沟通时，发送一封私密邮件，以友善的方式说明问题；
3. 升级处理：如果私下沟通后对方仍以非建设性方式回应，或者沟通没有产生预期效果，则应适当地上报给你的经理（escalate to your manager）。

注意升级是在前两步都无效之后的选择，切忌跳过沟通直接上报。

先修复代码，而不是先辩解

评审人说“看不懂你的某段代码”时，你的第一反应不应该是解释，而应该是澄清代码本身。文档给出了明确的优先级：

1. 澄清代码本身：优先修改代码，让它变得更容易理解；
2. 添加代码注释：如果代码无法进一步澄清，就加上一条解释“这段代码为什么存在”的注释；
3. 仅在评审工具中解释：只有当前两步都行不通（例如注释看起来毫无必要）时，才把解释写在代码评审工具的回复里。

为什么要坚持这个顺序？因为一个关键事实：如果评审人看不懂你的代码，那么未来阅读这段代码的人大概率也看不懂。在评审工具里写回复，无法帮助未来阅读代码的人；而澄清代码或添加代码注释，却能持续帮助所有后来的读者。

这与评审人一侧的指南完全对应：comments.md 中明确规定，当评审人要求开发者解释一段看不懂的代码时，正确的回应通常是把代码重写得更加清晰，偶尔也可以在代码中添加注释（前提是注释不是在为过度复杂的代码找借口）——只写在评审工具里的解释，对未来代码读者毫无帮助，仅在评审人不熟悉某个领域、而开发者解释的是普通读者本应已知的内容等少数情况下才被接受。

协作式思考，而非对抗式思考

写一个 CL 往往要耗费大量精力。当你终于把它送出去评审、觉得大功告成、确信不需要再改动时，收到要求修改的评论——尤其当你不同意这些评论时——确实令人沮丧。

此时，请后退一步，思考评审人是否在提供对代码库有价值的反馈。你问自己的第一个问题永远应该是：

“我是否理解评审人想要什么？”

如果答不上来，就去向评审人请求澄清。

理解但不同意时：协作而非对抗

如果你理解了评论但不同意，重要的是以协作的方式思考，而不是对抗或防御的方式。文档给出了一个正反面对比示例：

错误示范：

“不，我不会那样做。”

正确示范：

“我之所以选择 X，是因为［这些利弊权衡］。我的理解是，采用 Y 会更糟，因为［这些原因］。你是在建议 Y 能更好地服务于最初的权衡目标，还是我们应该重新评估权衡的权重，又或者是其他想法？”

注意正确示范的结构：先说明自己选择的理由和权衡，再请求对方澄清其意图——这是把“对抗”转化为“对齐目标”的关键话术。

文档同时强调，礼貌与尊重永远是第一优先级。如果你不同意评审人，请寻找协作的方式：请求澄清、讨论利弊、解释为什么你的做法对代码库、用户更有利。

你有评审人不知道的信息时

有时你可能掌握评审人不知道的关于用户、代码库或 CL 的信息。此时的做法是：

• 在合适的地方修复代码（见上文“先修复代码”原则）；
• 同时与评审人展开讨论，把更多上下文提供给对方。

基于技术事实，你和评审人通常能够达成某种共识。这条原则与 The Standard of Code Review 中的首要原则相呼应：技术事实和数据优先于个人观点和偏好——这意味着在争论中，最有说服力的论据永远是客观的技术依据。

解决冲突：从共识到升级

当意见分歧无法调和时，你的第一步永远是与评审人达成共识。如果无法达成共识，请参阅 The Standard of Code Review，该文档给出了此类情况下应遵循的原则。

评审标准一方的依据

作为 CL 作者，理解评审人一侧的判定标准有助于你判断“该坚持还是该让步”。standard.md 的核心原则是：

一般而言，只要一个 CL 处于明确能改善系统整体代码健康度的状态，评审人就应倾向于批准它，即使这个 CL 并不完美。

与之相关的事实是：

• 不存在“完美”的代码，只有“更好”的代码；评审人不应要求作者在批准前打磨每一个微小的细节；
• 评审人可以自由留下“可以做得更好”的评论，但如果并不重要，会加上“Nit: ”前缀，表示这只是可选打磨点，作者可以选择忽略；
• 如果评审人纯粹出于教学目的评论（帮助你学习新知识），而它并非达标必需，也会用 “Nit: ” 或类似方式注明非强制。

理解这些规则后，你就可以分辨：带 “Nit:” 的评论是可选优化，而不带前缀的评论更可能是必须解决的关键问题。

达成共识困难时的升级路径

虽然 handling-comments.md 本身只将冲突处理指向评审标准文档，但 standard.md 给出了完整的升级路径，可作为实际操作的补充：

1. 再次尝试共识：基于本文档、CL 作者指南 和 评审人指南 的内容再次协商；
2. 面对面或视频会议：当仅靠评论往来难以达成共识时，评审人与作者开一次面对面或视频会议通常很有帮助——如果这样做，务必把讨论结果作为评论记录在 CL 上，供未来读者参考；
3. 升级决策：最常见的升级路径包括：扩大到团队讨论、请技术负责人（Technical Lead）介入、请代码维护者（maintainer）裁决、或请工程经理（Eng Manager）协助。

标准文档还特别提醒：不要让 CL 因为作者和评审人无法达成一致而一直搁置（Don't let a CL sit around）。长时间挂起的 CL 既阻塞功能上线，也拖累团队效率。

把本文放回整个评审流程中

处理评审意见只是 CL 生命周期的一环。为了让评审环节更顺畅，以下相邻实践值得与你正在阅读的这份指南配套使用：

• Small CLs：小而聚焦的 CL 被评审更快、更彻底、更少引入 bug、更容易合并与回滚；评审人对“过大”的 CL 有权直接拒绝。小 CL 减少意见分歧的规模和频次，是“少吵架”的源头手段；
• Writing Good CL Descriptions：清晰的第一行（祈使句摘要）+ 信息丰富的正文，能让评审人和未来读者快速理解变更意图，减少“看不懂”类评论；
• The CL Author's Guide：开发者通过评审的完整指南集合；
• How to Do a Code Review：评审人一方的完整指南，理解评审人视角有助于你更好地回应。

小结

处理评审意见可以概括为一条行动主线：

1. 心态：把批评视为帮助，绝不愤怒回复；不友善反馈先私下沟通，无效再升级；
2. 行动：评审人看不懂代码时，先改代码、再加注释，最后才考虑在评审工具里解释；
3. 沟通：先确认自己是否理解意见，不理解就请求澄清；不同意时以协作方式讨论利弊、给出技术依据，而非对抗；
4. 冲突：第一步永远是达成共识；无法共识时参照 The Standard of Code Review 的原则，必要时升级给技术负责人、维护者或工程经理，避免 CL 无限期搁置。

掌握这套方法，你不仅能更快通过评审，也能让每一次评审对话成为代码库质量与团队协作能力的正向积累。

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