code-review-excellence

卓越的代码审查

通过建设性反馈、系统化分析和协作改进，将代码审查从把关转变为知识共享。

适用场景

• 审查拉取请求和代码变更
• 为团队制定代码审查标准
• 通过审查指导初级开发者
• 开展架构审查
• 编写审查清单和指南
• 改进团队协作
• 缩短代码审查周期
• 维护代码质量标准

核心原则

1. 审查心态

代码审查的目标：

• 发现 Bug 和边缘情况
• 确保代码易于维护
• 在团队中共享知识
• 执行编码标准
• 改进设计和架构
• 培养团队文化

非目标：

• 卖弄知识
• 吹毛求疵地纠结格式（使用代码检查工具）
• 不必要地阻碍进度
• 按照自己的偏好重写代码

2. 有效反馈

好的反馈应当：

• 具体且可操作
• 具有指导性，而非评判性
• 聚焦代码，而非个人
• 兼顾平衡（也要肯定优秀的工作）
• 区分优先级（关键问题与锦上添花的建议）

❌ Bad: "This is wrong."
✅ Good: "This could cause a race condition when multiple users
access simultaneously. Consider using a mutex here."

❌ Bad: "Why didn't you use X pattern?"
✅ Good: "Have you considered the Repository pattern? It would
make this easier to test. Here's an example: [link]"

❌ Bad: "Rename this variable."
✅ Good: "[nit] Consider `userCount` instead of `uc` for
clarity. Not blocking if you prefer to keep it."

3. 审查范围

应审查的内容：

• 逻辑正确性和边缘情况
• 安全漏洞
• 性能影响
• 测试覆盖率和质量
• 错误处理
• 文档和注释
• API 设计和命名
• 与架构的契合度

不应手动审查的内容：

• 代码格式（使用 Prettier、Black 等工具）
• 导入语句的组织
• 代码检查违规项
• 简单的拼写错误

审查流程

阶段 1：收集背景信息（2-3 分钟）

Before diving into code, understand:

1. Read PR description and linked issue
2. Check PR size (>400 lines? Ask to split)
3. Review CI/CD status (tests passing?)
4. Understand the business requirement
5. Note any relevant architectural decisions

阶段 2：高层次审查（5-10 分钟）

1. **Architecture & Design**
   - Does the solution fit the problem?
   - Are there simpler approaches?
   - Is it consistent with existing patterns?
   - Will it scale?

2. **File Organization**
   - Are new files in the right places?
   - Is code grouped logically?
   - Are there duplicate files?

3. **Testing Strategy**
   - Are there tests?
   - Do tests cover edge cases?
   - Are tests readable?

阶段 3：逐行审查（10-20 分钟）

For each file:

1. **Logic & Correctness**
   - Edge cases handled?
   - Off-by-one errors?
   - Null/undefined checks?
   - Race conditions?

2. **Security**
   - Input validation?
   - SQL injection risks?
   - XSS vulnerabilities?
   - Sensitive data exposure?

3. **Performance**
   - N+1 queries?
   - Unnecessary loops?
   - Memory leaks?
   - Blocking operations?

4. **Maintainability**
   - Clear variable names?
   - Functions doing one thing?
   - Complex code commented?
   - Magic numbers extracted?

阶段 4：总结与决策（2-3 分钟）

1. Summarize key concerns
2. Highlight what you liked
3. Make clear decision:
   - ✅ Approve
   - 💬 Comment (minor suggestions)
   - 🔄 Request Changes (must address)
4. Offer to pair if complex

撰写审查反馈前，请阅读 references/review-techniques.md，了解清单、问题措辞、协作和严重性判定技巧。

进行特定语言、架构、测试质量或安全审查前，请阅读 references/review-patterns.md，了解审查模式和清单。

提出较难接受的反馈

模式：改良版三明治法

Traditional: Praise + Criticism + Praise (feels fake)

Better: Context + Specific Issue + Helpful Solution

Example:
"I noticed the payment processing logic is inline in the
controller. This makes it harder to test and reuse.

[Specific Issue]
The calculateTotal() function mixes tax calculation,
discount logic, and database queries, making it difficult
to unit test and reason about.

[Helpful Solution]
Could we extract this into a PaymentService class? That
would make it testable and reusable. I can pair with you
on this if helpful."

处理分歧

When author disagrees with your feedback:

1. **Seek to Understand**
   "Help me understand your approach. What led you to
   choose this pattern?"

2. **Acknowledge Valid Points**
   "That's a good point about X. I hadn't considered that."

3. **Provide Data**
   "I'm concerned about performance. Can we add a benchmark
   to validate the approach?"

4. **Escalate if Needed**
   "Let's get [architect/senior dev] to weigh in on this."

5. **Know When to Let Go**
   If it's working and not a critical issue, approve it.
   Perfection is the enemy of progress.

最佳实践

1. 及时审查：在 24 小时内完成，最好当天完成
2. 控制 PR 规模：最多 200-400 行，便于有效审查
3. 分时段审查：每次最多 60 分钟，并适当休息
4. 使用审查工具：GitHub、GitLab 或专用工具
5. 尽可能自动化：代码检查工具、格式化工具、安全扫描
6. 建立融洽关系：表情符号、赞赏和同理心都很重要
7. 保持协助：主动提出结对解决复杂问题
8. 向他人学习：审查他人的审查评论

常见误区

• 完美主义：因细微的风格偏好而阻止 PR
• 范围蔓延：“既然你在改这个，能不能顺便……”
• 标准不一：对不同的人采用不同标准
• 延迟审查：让 PR 放置数天
• 失联：要求对方修改后便不再跟进
• 走过场：没有实际审查就批准
• 无谓争论：长时间纠结琐碎细节

模板

PR 审查评论模板

## Summary

[Brief overview of what was reviewed]

## Strengths

- [What was done well]
- [Good patterns or approaches]

## Required Changes

🔴 [Blocking issue 1]
🔴 [Blocking issue 2]

## Suggestions

💡 [Improvement 1]
💡 [Improvement 2]

## Questions

❓ [Clarification needed on X]
❓ [Alternative approach consideration]

## Verdict

✅ Approve after addressing required changes