Back to Details

engineering-review-feedback

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Engineering Review Feedback

工程代码评审反馈处理指南

Handle reviewer feedback as collaboration toward better code. The best response often changes the code, tests, or comments so future readers benefit, rather than explaining only inside the review thread.
Adapted from Google Engineering Practices Documentation, especially "How to handle reviewer comments." Source: https://google.github.io/eng-practices/review/developer/handling-comments.html. License: CC-BY 3.0.
将处理评审者反馈视为协作优化代码的过程。最佳回应方式通常是修改代码、测试或注释，让未来的阅读者受益，而非仅在评审线程中进行解释。
改编自谷歌工程实践文档，尤其是《如何处理评审意见》一文。来源：https://google.github.io/eng-practices/review/developer/handling-comments.html。许可证：CC-BY 3.0。

Response Workflow

回应工作流

  1. Pause before responding if the comment feels frustrating.
  2. Identify what the reviewer is asking for.
  3. Classify each comment:
    • Code change required.
    • Test change required.
    • Documentation or comment change required.
    • Clarification needed.
    • Disagreement to discuss.
    • Non-blocking suggestion.
  4. Prefer improving the artifact over explaining in the review tool.
  5. Run the relevant verification.
  6. Reply with what changed, why, and how it was tested.
If a reviewer says they do not understand the code, first try to make the code clearer. Add a code comment only when the why cannot be expressed cleanly in code.
  1. 若对评审意见感到沮丧，请先暂停再回复。
  2. 明确评审者的诉求。
  3. 对每条意见进行分类：
    • 需要修改代码。
    • 需要修改测试。
    • 需要修改文档或注释。
    • 需要澄清疑问。
    • 需要讨论分歧。
    • 非阻塞性建议。
  4. 优先优化代码本身，而非仅在评审工具中解释。
  5. 运行相关验证流程。
  6. 回复时说明修改内容、原因及测试方式。
如果评审者表示无法理解代码，首先尝试让代码更清晰。只有当代码无法简洁表达背后逻辑时，再添加代码注释。

When You Agree

当你同意评审意见时

Use a short response and make the change.
text
Done. I renamed the helper to describe normalization rather than validation and updated the two call sites.

Tested with: npm test -- user-profile.test.ts
使用简短回复并完成修改。
text
已完成。我将辅助函数重命名为描述归一化而非验证，并更新了两处调用位置。

测试命令：npm test -- user-profile.test.ts

When You Need Clarification

当你需要澄清时

Ask for the missing decision or constraint. Avoid defensive wording.
text
I want to make sure I understand the concern. Are you asking for this to reject duplicate requests at the API boundary, or for the worker to make duplicate processing idempotent?
询问缺失的决策依据或约束条件。避免使用防御性措辞。
text
我想确认是否理解了你的顾虑。你是要求在API边界处拒绝重复请求，还是让工作者实现重复处理的幂等性？

When You Disagree

当你不同意评审意见时

Disagree by comparing tradeoffs, not by rejecting the person.
text
I chose X because it keeps the retry policy in one place and avoids a second queue state. My concern with Y is that it makes cancellation observable in two different layers.

If you think Y better serves the rollback requirement, I can switch to it. Is that the tradeoff you want prioritized?
If the reviewer provides better technical reasoning, accept it and adjust. If neither side can converge, move to a higher-bandwidth conversation and summarize the decision back in the review.
通过对比利弊来表达分歧，而非否定评审者本人。
text
我选择方案X是因为它将重试策略集中在一处，避免了第二种队列状态。我对方案Y的顾虑是它会让取消操作在两个不同层级可见。

如果你认为方案Y更能满足回滚需求，我可以切换到该方案。你是否希望优先考虑这一权衡？
如果评审者提供了更充分的技术理由，请接受并调整方案。若双方无法达成共识，转向更高频的沟通方式，并将决策结果总结到评审线程中。

When Feedback Is Not Constructive

当反馈不具建设性时

Do not reply in kind. Extract any technical concern that can be addressed in code, tests, or docs. If the comment is hostile, vague, or repeatedly unproductive, move to a private or higher-bandwidth conversation, involve a lead when needed, and summarize only the technical decision back in the review.
不要以牙还牙。提取所有可通过修改代码、测试或文档解决的技术问题。若评论带有敌意、模糊不清或反复无意义，转向私下或更高频的沟通，必要时请负责人介入，并仅将技术决策结果总结到评审线程中。

Fix the Right Place

修复正确的问题点

  • Confusing expression: simplify or rename it.
  • Hidden invariant: encode it in types, validation, assertions, or a focused comment.
  • Missing behavior confidence: add or improve tests.
  • Missing context: update the PR description, code comment, README, or design doc.
  • Reviewer misunderstanding caused by stale diff: rebase, remove dead code, or update the description.
  • Pure preference: ask whether it is required; otherwise treat as optional.
  • 表达模糊：简化或重命名。
  • 隐藏不变量：通过类型定义、验证、断言或针对性注释来明确。
  • 行为信心不足：添加或改进测试。
  • 上下文缺失：更新PR描述、代码注释、README或设计文档。
  • 因差异过时导致评审者误解：重新变基、移除死代码或更新描述。
  • 纯个人偏好：询问是否为强制要求；否则视为可选。

Summary Reply Template

总结回复模板

markdown
Addressed this round:
- Changed ...
- Added/updated tests for ...
- Clarified ...

Verification:
- `...`

Open:
- ...
markdown
本轮已处理：
- 修改了...
- 添加/更新了针对...的测试
- 澄清了...

验证情况：
- `...`

待处理：
- ...

Common Mistakes

常见错误

  • Replying in anger or with sarcasm.
  • Explaining confusing code only in the review thread.
  • Treating every reviewer suggestion as mandatory without clarifying severity.
  • Saying "will clean up later" when the current change introduces the complexity.
  • Making broad unrelated refactors while addressing a narrow review comment.
  • 带着愤怒或讽刺回复。
  • 仅在评审线程中解释晦涩的代码。
  • 未经澄清严重程度就将所有评审建议视为必须执行。
  • 当前变更引入复杂性时却说“以后再清理”。
  • 在处理特定评审意见时进行宽泛的无关重构。