Code Review

Why Tone Matters in Code Review (代码评审为什么要注意语气)

Code review comments are written, public, and permanent. A comment that sounds neutral in your head can read as harsh on screen. The goal is to improve the code without making the author feel attacked.

代码评审的评论是书面的、公开的、永久保存的。在你脑中听起来中性的评论，在屏幕上可能显得很刻薄。目标是改善代码，而不是让作者觉得被攻击。

Golden rule 黄金法则: Be hard on the code, soft on the person. 对代码严格，对人温和。

Categorizing Your Comments (给评论分类)

Many teams use prefixes to signal how serious a comment is:

很多团队会用前缀来标注评论的严重程度：

• nit: — nitpick, optional. 小问题，可选改进。
• suggestion: — Take it or leave it. 建议，作者自行决定。
• question: — I'm just asking, not asserting. 我在问，不是断言。
• issue: — This needs to change. 这个需要改。
• blocking: — Cannot merge until fixed. 必须修了才能合并。

Example: nit: typo in the comment above — 小问题：上面注释里有个错字。

Suggesting Changes (建议修改)

Soft suggestions (软建议)

• "What do you think about extracting this into a helper?" — 你觉得把这部分抽成一个 helper 函数怎么样？
• "Have you considered using X here?" — 你考虑过这里用 X 吗？
• "Would it make sense to..." — 会不会更合理一些……
• "It might be cleaner to..." — 可能更清晰的写法是……
• "One option could be..." — 一种做法可以是……
• "Just a thought: ..." — 一个小想法：……

Direct but kind (直接但友好)

• "I'd suggest renaming this to X for clarity." — 我建议把这个改名为 X 以便更清晰。
• "Let's pull this out into a separate function." — 我们把这部分抽出来作为单独的函数吧。
• "This should probably be in a try/catch." — 这里应该放在 try/catch 里。

Blocking issues (必改问题)

• "This will break in production because..." — 这会在生产环境出问题，因为……
• "We need to handle the null case here." — 这里需要处理 null 的情况。
• "This introduces a security issue: ..." — 这里引入了安全问题：……
• "Blocking: this needs tests before merging." — 阻塞：合并前需要加测试。

Asking Questions (提问)

When you're unsure, ask instead of assuming. The author has context you don't.

不确定时要问，而不是假设。作者有你没有的上下文。

• "What's the reason for X here?" — 这里为什么要这样写？
• "Could you help me understand why..." — 能帮我理解一下为什么……
• "I might be missing context — why X over Y?" — 我可能缺少上下文——为什么选 X 而不是 Y？
• "Is there a reason we're not using the existing helper?" — 有什么原因不用现有的 helper 吗？
• "Just to make sure I understand: this means..., right?" — 确认一下我理解：这是说……，对吗？

Pointing Out Bugs (指出 bug)

• "I think this might fail when X is empty." — 我觉得当 X 为空时这里可能会出错。
• "What happens if X is null?" — 如果 X 是 null 会发生什么？
• "This looks like a race condition." — 这看起来像是个竞态条件。
• "There's an off-by-one error here." — 这里有个差一错误。
• "This won't handle the edge case where..." — 这里没处理 …… 的边界情况。

Praise (表扬)

Don't just leave critical comments — point out good code too. Praise reinforces good practices.

不要只留批评意见——好的代码也要夸。表扬能强化好的实践。

• "Nice solution!" — 解决方案很赞！
• "Clean refactor 👏" — 重构得很干净 👏
• "Love this abstraction." — 喜欢这个抽象。
• "Great test coverage here." — 这里测试覆盖得很好。
• "TIL — didn't know about this API." — 学到了——之前不知道这个 API。
• "This is much cleaner than what I'd have written." — 这比我写的要干净多了。

Approval (通过)

• "LGTM!" — Looks good to me! 我看可以！(代码评审最常用)
• "LGTM with one small comment." — 整体可以，但有一个小意见。
• "Approving — leaving the nits to your discretion." — 通过——小问题你自己决定。(discretion = 自行决定)
• "Ship it! 🚀" — 发布吧！🚀
• "Approved, thanks for the quick turnaround." — 通过，谢谢这么快搞定。(turnaround = 完成时间)

Requesting Changes (请求修改)

• "Requesting changes — see comments." — 请求修改——见评论。
• "A few things to address before this is good to merge." — 合并前需要处理几个问题。
• "Mostly small things — easy to address." — 大部分是小问题，容易处理。

Receiving Comments (作为作者回应评论)

Accepting feedback (接受反馈)

• "Good catch, thanks!" — 抓得好，谢谢！(catch = 发现问题)
• "Nice catch — fixed." — 发现得好——已修。
• "You're right, updating now." — 你说得对，正在改。
• "Makes sense. Will refactor." — 有道理，我会重构。
• "TIL, thanks for the explanation." — 学到了，谢谢解释。

Asking for clarification (请求澄清)

• "Could you clarify what you mean?" — 能澄清一下你的意思吗？
• "Not sure I follow — could you give an example?" — 我没太懂——能举个例子吗？
• "What would you suggest instead?" — 那你建议改成什么样？

Pushing back politely (礼貌反驳)

When the reviewer's suggestion isn't right, you can disagree — politely with reasoning.

当评审者的建议不对时，你可以不同意——但要礼貌且给出理由。

• "I considered that, but went with X because..." — 我考虑过那种方式，但选了 X 是因为……
• "Hmm, I'd actually push back on this — [reason]" — 嗯，我想保留意见——[原因]
• "I see your point, but in this case..." — 我理解你的意思，但这种情况下……
• "Happy to discuss further — could we sync briefly?" — 我们可以再聊聊——简短同步一下？
• "Could we keep it as-is for now and revisit in a follow-up?" — 可以暂时保留现状，后面再处理吗？

Deferring to follow-up (推迟到下次处理)

• "Good point — opening a follow-up ticket." — 说得好——我开个跟进的工单。
• "Out of scope for this PR, but I'll track it." — 超出这个 PR 范围了，但我会记着。
• "Filed as TODO for now." — 暂时标为 TODO 了。

Sample Code Review Comments (代码评审评论示例)

Suggesting a refactor (建议重构)

suggestion: This logic is repeated in userService.ts and adminService.ts. Worth pulling out into a shared utility?

建议：这个逻辑在 userService.ts 和 adminService.ts 都有。要不要抽成一个共享工具函数？

Pointing out a bug (指出 bug)

I think this will throw if user.email is undefined — could we add a guard? Saw it happen in [issue link].

我觉得如果 user.email 是 undefined 这里会抛错——能加个保护吗？在 [issue 链接] 见过这种情况。

A "nit" (小问题)

nit: typo — "recieve" should be "receive". Feel free to ignore if you want to merge first and fix later.

小问题：拼写——"recieve" 应该是 "receive"。如果想先合并以后再修也可以。

Praise + suggestion (表扬 + 建议)

Love how clean this is! One small thing — could we add a comment explaining the magic number 1000? Took me a sec to figure out it's the rate limit window.

写得真干净！一个小建议——能加个注释解释 1000 这个数字吗？我看了一下才意识到是限流窗口。

Common Code Review Vocabulary (常用代码评审词汇)

Tips (小贴士)

• Lead with questions, not commands — "What if we did X?" lands better than "Do X." 用提问代替命令。
• Explain the why — Don't just say "change this." Say why. 解释原因，不要只说"改成这样"。
• Praise publicly — A "nice work" comment costs nothing and means a lot. 公开表扬不花钱但很重要。
• Don't pile on — If 3 reviewers already pointed out the same nit, you don't need to add a fourth. 不要重复别人指出的问题。
• Approve with comments — If only nits are left, approve and let the author decide. 只剩小问题时，先通过让作者自己决定。