技术英语 / 系统课时
写自然的代码评审意见
写自然的代码评审意见
代码评审意见既要指出问题,也要让作者知道你在建议、提问还是要求修改。本篇聚焦四类高频表达:建议、质疑、确认和请求修改,帮助你把评论写得具体、礼貌,并避免只有 “Why?” 或 “Fix this.” 这样的生硬短句。
学习目标
- 能用不同句式区分建议、问题确认与必须修改的阻塞项。
- 能把评论落到具体代码行为、风险和可执行动作,而不是只给情绪化判断。
- 能在保持礼貌的同时明确评审结论,不用模糊措辞掩盖真实要求。
先说明你在做哪一种沟通
自然的评审意见通常包含两个部分:你观察到的事实,以及你希望作者接下来做什么。建议可以用 Could we...、Would it make sense to...;确认意图可以用 Is there a reason we...;需要修改时则直接说明风险和动作。
如果只是偏好,不要写成硬性要求。例如 Could we rename this to make the unit explicit? 表示建议;而 Please add a null check here because this path is reachable before authentication. 明确说明了修改要求与原因。
让评论紧贴具体代码
片段示例:下面的 diff 只是评审上下文,不是可独立运行的程序。
- const timeout = config.timeout || 30;
+ const timeout = config.timeout ?? 30;如果你关心的是 0 被当成默认值覆盖,可以写:Could we use the nullish coalescing operator here? A timeout of 0 is currently replaced with 30. 这比 Use ?? instead. 更自然,因为作者能同时看到建议、原因和行为差异。
当你不确定设计意图时,不要假设作者写错了。可以写:Is there a reason we treat 0 as missing here? I want to make sure the fallback is intentional. 这种表达把“质疑实现”改成“确认意图”,更适合尚未掌握完整上下文的评审者。
区分建议与阻塞项
评论是否必须处理,应在措辞中清楚体现。非阻塞建议可以使用 Could we...、Maybe we could... 或 It might be clearer to...。如果问题会导致错误、安全风险或测试失败,则应明确写出影响,不要只在语气上变得更强硬。
例如:Please handle the rejected promise before merging; otherwise this request can terminate without returning an error response. 这里的重点是“为什么必须改”,而不是使用更严厉的词。
避免生硬和模糊
Why did you do this? 容易让作者把注意力放在被质问的感觉上,可以改成 What led us to choose this approach? 或更具体的 Is this needed to preserve backward compatibility?。
This is confusing. 也缺少可执行信息。更好的写法是指出具体障碍,例如:I had trouble following the two boolean flags together. Could we replace them with a single status value? 这样作者知道你在哪里卡住,也知道可以尝试怎样修改。
Looks good, but maybe fix the tests. 同时包含肯定和模糊要求。若测试确实失败,应写清楚:The implementation looks good. The CI test for the empty-input case is still failing; please update the code or the test before merging.
用“事实、影响、动作”收束评论
当问题比较重要时,可以用一个稳定结构组织句子:先描述事实,再说明影响,最后提出动作。比如:This function retries every error, including 4xx responses. That can create unnecessary traffic for permanent failures. Could we retry only transient errors?
这种写法既不会弱化技术判断,也不会把评论变成人身评价。评审意见越接近代码行为、风险和下一步动作,越容易被准确理解和快速处理。