engineering-review-comments

工程评审评论

评审评论应帮助改进代码，并提升开发者今后的判断能力。评论应明确说明严重程度，以工程理由为依据，并针对代码而非个人。

改编自 Google Engineering Practices Documentation，尤其是“How to write code review comments”和“Handling pushback in code reviews”。来源：https://google.github.io/eng-practices/review/reviewer/comments.html。许可协议：CC-BY 3.0。

评论结构

对于非简单评论，使用以下结构：

SEVERITY: Observation about the code.

Why this matters: engineering reason, user impact, maintainability impact, or violated project rule.

Requested action: concrete fix, question, or decision the author needs to make.

简短的评论就保持简短。如果意图可能被误解，就使用完整结构。

严重程度标签

• BLOCKER：必须在批准前修改，因为正确性、可维护性、安全性、数据、测试或运维方面的风险不可接受。
• IMPORTANT：应在批准前修改；只有给出明确理由时才可以豁免。
• QUESTION：评审者需要了解更多信息才能做出判断。
• NIT：细微润色。不应因此阻止批准。
• OPTIONAL 或 CONSIDER：建议，作者可以不采纳。
• FYI：用于提供背景知识或提示未来需要考虑的事项；无需采取行动。

写作规则

• 评论代码、设计、测试或行为；不要评价作者。
• 当要求的内容超出显而易见的风格调整或机械式清理时，解释原因。
• 优先使用“这会让 X 更难，因为……”而不是“我不喜欢 X。”
• 如果需要在评审讨论串中解释普通行为，就要求简化代码。
• 只有当代码本身无法合理表达原因时，才接受代码注释。
• 只有在提供直接代码或具体设计比让作者自行推断更快或更安全时，才这样做。
• 否则，描述问题，让作者选择实现方式。
• 在有帮助时指出好的工程实践，并说明其优点。

措辞范例

在适用时，直接使用以下范例：

BLOCKER: This path can return success before the write is durable.

If the process crashes after this point, callers will believe the operation completed even though the data may be missing. Please either move the success response after the durable write or make the operation explicitly asynchronous and observable.

QUESTION: What guarantees that this callback cannot run concurrently?

If it can run in parallel, `pending` can be decremented twice from the same value. If the framework serializes this callback, please add a short comment at the boundary where that guarantee comes from.

NIT: This helper name reads as if it validates the payload, but it only normalizes whitespace. Could we rename it to `normalizePayloadText`?

OPTIONAL: Consider extracting this branch into a named helper. The current version is correct, but a helper would make the three policy cases easier to scan.

处理异议

作者表示不同意时：

1. 先重新评估对方的论点。他们可能更熟悉相关代码，或掌握你不了解的背景。
2. 如果他们说得对，就直截了当地承认并解决这条评论。
3. 如果你仍然不同意，先复述对方的观点，再解释你提出要求的代码健康方面的原因。
4. 区分强制要求和个人偏好。
5. 如果讨论串停滞不前，就转到更适合深入沟通的渠道，并在评审中总结决定。

不要因为你先发表了评论，就一直争论。目标是得到最好的代码，而不是维护最初的措辞。

常见错误

• 留下没有标注的评论，导致作者误以为必须照做。
• 提出正确的批评，却使用不利于协作的语气。
• 只在评审工具中要求作者解释令人困惑的代码。
• 把每条评论都变成完整的设计任务。
• 把教育性说明当作阻塞项。