如何优雅地处理评审意见Google Engineering Practices 中 CL 作者的代码评审沟通指南【免费下载链接】eng-practicesGoogles Engineering Practices documentation项目地址: https://gitcode.com/gh_mirrors/eng/eng-practices当你的 CLchangelist即一次自包含的代码变更其他团队也称之为 change、patch 或 pull-request术语见 README.md提交给评审人reviewer后几乎一定会收到若干条评审意见。如何处理这些意见直接决定了你的代码能否顺利合入、评审体验是否愉快以及代码库的整体健康度。本文基于 Google Engineering Practices 文档中的 handling-comments.md 展开从心态调整、代码修复、协作式沟通到冲突升级给出 CL 作者在评审各阶段可立即落地的完整行动指南帮助你更快通过评审并获得更高质量的评审结果。本指南属于 The CL Authors Guide 三篇系列文档之一另两篇是 Writing Good CL Descriptions 与 Small CLs同时与评审人一侧的 How to Write Code Review Comments、The Standard of Code Review 互为镜像建议对照阅读。不要把它当成针对你个人的攻击评审的目标是维护代码库和产品的质量。当评审人对你的代码提出批评时请把它视为评审人试图帮助你、帮助代码库的行为而不是对你个人或你能力的攻击。即使是最优秀的工程师也偶尔会遇到情绪化的评审意见。文档明确指出评审人在评论中流露沮丧情绪并非良好实践但作为开发者你应当对此有所准备。遇到这类评论时先问自己一个问题“评审人真正想传达给我的、有建设性的内容是什么”然后按照这个建设性意图去理解和行动忽略语气上的不友善。永远不要在愤怒中回复评审意见这是文档强调的职业底线永远不要在愤怒中回复代码评审评论。在愤怒状态下回复是对职业礼仪的严重破坏而且这段对话会永久保存在代码评审工具的历史记录里被后续所有人看到。如果你过于愤怒或烦躁、无法友善地回复正确做法是暂时离开电脑一段时间或者先去做别的事情等到情绪平复到足以礼貌回复时再回来。评审人不友善时的处理路径如果评审人提供的反馈总体上不具建设性、不够礼貌文档给出的处理路径是分级的当面沟通当面或视频通话向评审人解释你不喜欢什么、希望对方怎样改变私下邮件无法当面沟通时发送一封私密邮件以友善的方式说明问题升级处理如果私下沟通后对方仍以非建设性方式回应或者沟通没有产生预期效果则应适当地上报给你的经理escalate to your manager。注意升级是在前两步都无效之后的选择切忌跳过沟通直接上报。先修复代码而不是先辩解评审人说“看不懂你的某段代码”时你的第一反应不应该是解释而应该是澄清代码本身。文档给出了明确的优先级澄清代码本身优先修改代码让它变得更容易理解添加代码注释如果代码无法进一步澄清就加上一条解释“这段代码为什么存在”的注释仅在评审工具中解释只有当前两步都行不通例如注释看起来毫无必要时才把解释写在代码评审工具的回复里。为什么要坚持这个顺序因为一个关键事实如果评审人看不懂你的代码那么未来阅读这段代码的人大概率也看不懂。在评审工具里写回复无法帮助未来阅读代码的人而澄清代码或添加代码注释却能持续帮助所有后来的读者。这与评审人一侧的指南完全对应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 给出了完整的升级路径可作为实际操作的补充再次尝试共识基于本文档、CL 作者指南 和 评审人指南 的内容再次协商面对面或视频会议当仅靠评论往来难以达成共识时评审人与作者开一次面对面或视频会议通常很有帮助——如果这样做务必把讨论结果作为评论记录在 CL 上供未来读者参考升级决策最常见的升级路径包括扩大到团队讨论、请技术负责人Technical Lead介入、请代码维护者maintainer裁决、或请工程经理Eng Manager协助。标准文档还特别提醒不要让 CL 因为作者和评审人无法达成一致而一直搁置Dont let a CL sit around。长时间挂起的 CL 既阻塞功能上线也拖累团队效率。把本文放回整个评审流程中处理评审意见只是 CL 生命周期的一环。为了让评审环节更顺畅以下相邻实践值得与你正在阅读的这份指南配套使用Small CLs小而聚焦的 CL 被评审更快、更彻底、更少引入 bug、更容易合并与回滚评审人对“过大”的 CL 有权直接拒绝。小 CL 减少意见分歧的规模和频次是“少吵架”的源头手段Writing Good CL Descriptions清晰的第一行祈使句摘要 信息丰富的正文能让评审人和未来读者快速理解变更意图减少“看不懂”类评论The CL Authors Guide开发者通过评审的完整指南集合How to Do a Code Review评审人一方的完整指南理解评审人视角有助于你更好地回应。小结处理评审意见可以概括为一条行动主线心态把批评视为帮助绝不愤怒回复不友善反馈先私下沟通无效再升级行动评审人看不懂代码时先改代码、再加注释最后才考虑在评审工具里解释沟通先确认自己是否理解意见不理解就请求澄清不同意时以协作方式讨论利弊、给出技术依据而非对抗冲突第一步永远是达成共识无法共识时参照 The Standard of Code Review 的原则必要时升级给技术负责人、维护者或工程经理避免 CL 无限期搁置。掌握这套方法你不仅能更快通过评审也能让每一次评审对话成为代码库质量与团队协作能力的正向积累。【免费下载链接】eng-practicesGoogles Engineering Practices documentation项目地址: https://gitcode.com/gh_mirrors/eng/eng-practices创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考