代码审查卓越实践

通过建设性反馈、系统性分析与协作式改进，将代码审查从“守门”转变为“知识共享”。

适用场景

• 审查 Pull Request 和代码变更
• 为团队建立代码审查标准
• 通过审查指导初级开发者
• 开展架构审查
• 制定审查清单与指南
• 提升团队协作效率
• 缩短代码审查周期
• 维护代码质量标准

核心原则

1. 审查思维模式

代码审查的目标：

• 发现缺陷与边界情况
• 保障代码可维护性
• 促进团队间知识共享
• 落实编码规范
• 优化设计与架构
• 塑造积极的团队文化

非审查目标：

• 炫耀个人知识
• 纠结格式细节（应交由 linter 处理）
• 无必要地阻碍进度
• 按个人偏好重写代码

2. 高效反馈

优质反馈的特征：

• 具体且可操作
• 具有教育意义，而非主观评判
• 聚焦于代码本身，而非提交者本人
• 保持平衡（同时肯定优秀实践）
• 明确优先级（关键问题 vs 可选建议）

❌ 不佳："这个是错的。"
✅ 优良："当多个用户同时访问时，此处可能引发竞态条件。建议在此处使用 mutex。"

❌ 不佳："你为什么没用 X 模式？"
✅ 优良："你考虑过 Repository 模式吗？它会让这部分代码更易于测试。参考示例：[link]"

❌ 不佳："把这个变量重命名。"
✅ 优良："[nit] 建议将 `uc` 改为 `userCount` 以提升可读性。若你倾向保留原名，此条不构成阻塞。"

3. 审查范围

应当审查的内容：

• 逻辑正确性与边界情况
• 安全漏洞
• 性能影响
• 测试覆盖率与质量
• 错误处理机制
• 文档与注释
• API 设计与命名规范
• 是否符合整体架构

无需人工审查的内容：

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

审查流程

阶段 1：上下文收集（2–3 分钟）

深入代码前，请先理解以下信息：

1. 阅读 PR 描述及关联 issue
2. 评估 PR 规模（超过 400 行？建议拆分）
3. 检查 CI/CD 状态（测试是否全部通过？）
4. 明确业务需求背景
5. 记录相关架构决策

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

1. 架构与设计 —— 解决方案是否契合问题本质？
   • 针对重大变更，请参阅《Architecture Review Guide》
   • 检查：SOLID 原则、耦合度/内聚度、反模式
2. 性能评估 —— 是否存在性能隐患？
   • 针对性能敏感代码，请参阅《Performance Review Guide》
   • 检查：算法时间复杂度、N+1 查询、内存占用
3. 文件组织结构 —— 新增文件是否置于合理位置？
4. 测试策略 —— 是否覆盖关键边界场景？

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

对每个文件依次核查：

• 逻辑与正确性 —— 边界情况、索引越界、空值检查、竞态条件
• 安全性 —— 输入校验、注入风险、XSS、敏感数据泄露
• 性能 —— N+1 查询、冗余循环、内存泄漏
• 可维护性 —— 命名清晰、单一职责、注释恰当

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

1. 归纳关键问题
2. 指出值得肯定之处
3. 给出明确结论：
   • ✅ 批准通过
   • 💬 补充评论（轻微建议）
   • 🔄 请求修改（必须解决）
4. 如涉及复杂问题，主动提出结对审查

审查技巧

技巧 1：清单法（Checklist Method）

借助标准化清单确保审查一致性。详见《Security Review Guide》中提供的完整安全审查清单。

技巧 2：提问式审查（Question Approach）

避免直接指出问题，改用提问引导思考：

❌ "列表为空时此处会失败。"
✅ "如果 `items` 是一个空数组，会发生什么？"

❌ "此处需要增加错误处理。"
✅ "若 API 调用失败，这段逻辑应如何响应？"

技巧 3：建议而非指令（Suggest, Don't Command）

采用协作性语言表达意见：

❌ "你必须将此处改为 async/await"
✅ "建议：async/await 或许能提升可读性。你怎么看？"

❌ "请将这段逻辑抽取为函数"
✅ "该逻辑在 3 处重复出现，是否适合抽取为独立函数？"

技巧 4：区分问题严重等级

使用标签标识优先级：

• 🔴 [blocking] —— 必须修复后方可合并
• 🟡 [important] —— 应当修复；如有异议需讨论
• 🟢 [nit] —— 改进项，非阻塞项
• 💡 [suggestion] —— 值得考虑的替代方案
• 📚 [learning] —— 教育性说明，无需操作
• 🎉 [praise] —— 表扬亮点，继续保持！

语言专项指南

根据被审查代码所使用的语言或框架，查阅对应详细指南：

延伸资源

• Architecture Review Guide — 架构设计审查指南（SOLID、反模式、耦合度）
• Performance Review Guide — 性能审查指南（Web Vitals、N+1、复杂度）
• Common Bugs Checklist — 按语言分类的常见错误清单
• Security Review Guide — 安全审查指南
• Code Review Best Practices — 代码审查最佳实践
• PR Review Template — PR 审查评论模板
• Review Checklist — 快速参考清单