code-review-excellence

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Review Excellence

卓越代码审查实践

Transform code reviews from gatekeeping to knowledge sharing through constructive feedback, systematic analysis, and collaborative improvement.

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

When to Use This Skill

适用场景

Reviewing pull requests and code changes
Establishing code review standards for teams
Mentoring junior developers through reviews
Conducting architecture reviews
Creating review checklists and guidelines
Improving team collaboration
Reducing code review cycle time
Maintaining code quality standards

审查拉取请求（pull requests）与代码变更
为团队制定代码审查标准
通过审查指导初级开发者
开展架构审查
创建审查清单与指南
提升团队协作效率
缩短代码审查周期
维护代码质量标准

Core Principles

核心原则

1. The Review Mindset

1. 审查心态

Goals of Code Review:

Catch bugs and edge cases
Ensure code maintainability
Share knowledge across team
Enforce coding standards
Improve design and architecture
Build team culture

Not the Goals:

Show off knowledge
Nitpick formatting (use linters)
Block progress unnecessarily
Rewrite to your preference

代码审查目标：

捕获Bug与边缘案例
确保代码可维护性
在团队内共享知识
执行编码标准
优化设计与架构
构建团队文化

非审查目标：

炫耀个人知识
挑剔格式问题（使用代码格式化工具）
无故阻碍进度
按个人偏好重写代码

2. Effective Feedback

2. 有效反馈

Good Feedback is:

Specific and actionable
Educational, not judgmental
Focused on the code, not the person
Balanced (praise good work too)
Prioritized (critical vs nice-to-have)

markdown

❌ 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."

优质反馈的特点：

具体且可执行
具有教育意义，而非评判性
聚焦代码而非个人
平衡（也要表扬优秀工作）
区分优先级（关键问题 vs 锦上添花的建议）

markdown

❌ 糟糕示例："这是错的。"
✅ 优秀示例："当多个用户同时访问时，这可能会引发竞态条件。建议在此处使用互斥锁（mutex）。"

❌ 糟糕示例："你为什么不使用X模式？"
✅ 优秀示例："你是否考虑过Repository模式？它会让这段代码更易于测试。示例链接：[link]"

❌ 糟糕示例："重命名这个变量。"
✅ 优秀示例："[细节优化] 为了清晰起见，建议将`uc`改为`userCount`。若你偏好保留原命名，无需修改即可合并。"

3. Review Scope

3. 审查范围

What to Review:

Logic correctness and edge cases
Security vulnerabilities
Performance implications
Test coverage and quality
Error handling
Documentation and comments
API design and naming
Architectural fit

What Not to Review Manually:

Code formatting (use Prettier, Black, etc.)
Import organization
Linting violations
Simple typos

需要审查的内容：

逻辑正确性与边缘案例
安全漏洞
性能影响
测试覆盖度与质量
错误处理
文档与注释
API设计与命名
架构适配性

无需手动审查的内容：

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

Review Process

审查流程

Phase 1: Context Gathering (2-3 minutes)

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

Before diving into code, understand:

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

深入代码之前，需了解：

阅读PR描述及关联的Issue
检查PR规模（超过400行？建议拆分）
查看CI/CD状态（测试是否通过？）
理解业务需求
记录相关的架构决策

Phase 2: High-Level Review (5-10 minutes)

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

Architecture & Design - Does the solution fit the problem?
- For significant changes, consult Architecture Review Guide
- Check: SOLID principles, coupling/cohesion, anti-patterns
Performance Assessment - Are there performance concerns?
- For performance-critical code, consult Performance Review Guide
- Check: Algorithm complexity, N+1 queries, memory usage
File Organization - Are new files in the right places?
Testing Strategy - Are there tests covering edge cases?

架构与设计 - 解决方案是否匹配问题？
- 对于重大变更，请参考《架构审查指南》（Architecture Review Guide）
- 检查：SOLID原则、耦合度/内聚度、反模式
性能评估 - 是否存在性能隐患？
- 对于性能敏感代码，请参考《性能审查指南》（Performance Review Guide）
- 检查：算法复杂度、N+1查询、内存占用
文件组织 - 新文件是否存放于正确位置？
测试策略 - 是否有覆盖边缘案例的测试？

Phase 3: Line-by-Line Review (10-20 minutes)

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

For each file, check:

Logic & Correctness - Edge cases, off-by-one, null checks, race conditions
Security - Input validation, injection risks, XSS, sensitive data
Performance - N+1 queries, unnecessary loops, memory leaks
Maintainability - Clear names, single responsibility, comments
Reuse - Before accepting new code, search for existing utilities/helpers that could replace it. Check adjacent files and shared modules for similar patterns. See Universal Quality Guide for anti-patterns like parameter sprawl, leaky abstractions, nested conditionals, stringly-typed code, TOCTOU, and no-op updates.

针对每个文件，检查：

逻辑与正确性 - 边缘案例、差一错误、空值检查、竞态条件
安全性 - 输入验证、注入风险、XSS、敏感数据
性能 - N+1查询、不必要的循环、内存泄漏
可维护性 - 清晰的命名、单一职责、注释
复用性 - 在接受新代码之前，搜索是否存在可替代的现有工具/辅助函数。检查相邻文件和共享模块是否有类似模式。参考《通用质量指南》（Universal Quality Guide）了解参数膨胀、抽象泄漏、嵌套条件、字符串类型化代码、TOCTOU、无操作更新等反模式。

Phase 4: Summary & Decision (2-3 minutes)

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

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

总结关键问题
突出优点
给出明确决策：
- ✅ 批准
- 💬 评论（次要建议）
- 🔄 请求修改（必须解决）
若涉及复杂内容，可提议结对审查

Review Techniques

审查技巧

Technique 1: The Checklist Method

技巧1：清单法

Use checklists for consistent reviews. See Security Review Guide for comprehensive security checklist.

使用清单确保审查一致性。如需全面的安全审查清单，请参考《安全审查指南》（Security Review Guide）。

Technique 2: The Question Approach

技巧2：提问法

Instead of stating problems, ask questions:

markdown

❌ "This will fail if the list is empty."
✅ "What happens if `items` is an empty array?"

❌ "You need error handling here."
✅ "How should this behave if the API call fails?"

不要直接指出问题，而是提出疑问：

markdown

❌ "如果列表为空，这段代码会失败。"
✅ "如果`items`是空数组，会发生什么情况？"

❌ "这里需要错误处理。"
✅ "如果API调用失败，这段代码应该如何处理？"

Technique 3: Suggest, Don't Command

技巧3：建议而非命令

Use collaborative language:

markdown

❌ "You must change this to use async/await"
✅ "Suggestion: async/await might make this more readable. What do you think?"

❌ "Extract this into a function"
✅ "This logic appears in 3 places. Would it make sense to extract it?"

使用协作性语言：

markdown

❌ "你必须改为使用async/await"
✅ "建议：使用async/await可能会让这段代码更具可读性。你觉得呢？"

❌ "把这段代码提取成函数"
✅ "这段逻辑出现在3个地方。提取成函数是否更合理？"

Technique 4: Differentiate Severity

技巧4：区分严重程度

Use labels to indicate priority:

🔴
```
[blocking]
```
- Must fix before merge
🟡
```
[important]
```
- Should fix, discuss if disagree
🟢
```
[nit]
```
- Nice to have, not blocking
💡
```
[suggestion]
```
- Alternative approach to consider
📚
```
[learning]
```
- Educational comment, no action needed
🎉
```
[praise]
```
- Good work, keep it up!

使用标签标识优先级：

🔴
```
[blocking]
```
- 合并前必须修复
🟡
```
[important]
```
- 应该修复，若有异议可讨论
🟢
```
[nit]
```
- 锦上添花的建议，不阻碍合并
💡
```
[suggestion]
```
- 可供参考的替代方案
📚
```
[learning]
```
- 教育性评论，无需采取行动
🎉
```
[praise]
```
- 优秀工作，继续保持！

Language-Specific Guides

语言专属指南

根据审查的代码语言，查阅对应的详细指南：

Language/Framework	Reference File	Key Topics
React	React Guide	Hooks, useEffect, React 19 Actions, RSC, Suspense, TanStack Query v5
Vue 3	Vue Guide	Composition API, 响应性系统, Props/Emits, Watchers, Composables
Angular 17+	Angular Guide	Signals, Standalone 组件, RxJS, Zoneless 变更检测, 模板优化
Rust	Rust Guide	所有权/借用, Unsafe 审查, 异步代码, 取消安全性, 错误处理
TypeScript	TypeScript Guide	类型安全, async/await, 不可变性
Python	Python Guide	可变默认参数, 异常处理, 类属性
Django / DRF	Django Guide	安全审查, N+1 查询, Serializer 反模式, ViewSet, 异步视图
Java	Java Guide	Java 17/21 新特性, Spring Boot 3, 虚拟线程, Stream/Optional
C# / .NET	C# Guide	C# 12 特性, 异步编程, EF Core 性能, ASP.NET Core, LINQ
Go	Go Guide	错误处理, goroutine/channel, context, 接口设计
Kotlin / Android	Kotlin Guide	协程, Flow, Jetpack Compose, 空安全, 内存泄漏, 架构模式
NestJS	NestJS Guide	依赖注入, 分层架构, DTO 验证, Guard/Interceptor, 循环依赖
Svelte / SvelteKit	Svelte Guide	Runes, Load 函数, Form Actions, Store 迁移, SSR/CSR 边界
C	C Guide	指针/缓冲区, 内存安全, UB, 错误处理
C++	C++ Guide	RAII, 生命周期, Rule of 0/3/5, 异常安全
CSS/Less/Sass	CSS Guide	变量规范, !important, 性能优化, 响应式, 兼容性
Qt	Qt Guide	对象模型, 信号/槽, 内存管理, 线程安全, 性能

根据审查的代码语言，查阅对应的详细指南：

语言/框架	参考文档	核心主题
React	React Guide	Hooks, useEffect, React 19 Actions, RSC, Suspense, TanStack Query v5
Vue 3	Vue Guide	Composition API, 响应性系统, Props/Emits, Watchers, Composables
Angular 17+	Angular Guide	Signals, Standalone 组件, RxJS, Zoneless 变更检测, 模板优化
Rust	Rust Guide	所有权/借用, Unsafe 审查, 异步代码, 取消安全性, 错误处理
TypeScript	TypeScript Guide	类型安全, async/await, 不可变性
Python	Python Guide	可变默认参数, 异常处理, 类属性
Django / DRF	Django Guide	安全审查, N+1 查询, Serializer 反模式, ViewSet, 异步视图
Java	Java Guide	Java 17/21 新特性, Spring Boot 3, 虚拟线程, Stream/Optional
C# / .NET	C# Guide	C# 12 特性, 异步编程, EF Core 性能, ASP.NET Core, LINQ
Go	Go Guide	错误处理, goroutine/channel, context, 接口设计
Kotlin / Android	Kotlin Guide	协程, Flow, Jetpack Compose, 空安全, 内存泄漏, 架构模式
NestJS	NestJS Guide	依赖注入, 分层架构, DTO 验证, Guard/Interceptor, 循环依赖
Svelte / SvelteKit	Svelte Guide	Runes, Load 函数, Form Actions, Store 迁移, SSR/CSR 边界
C	C Guide	指针/缓冲区, 内存安全, UB, 错误处理
C++	C++ Guide	RAII, 生命周期, Rule of 0/3/5, 异常安全
CSS/Less/Sass	CSS Guide	变量规范, !important, 性能优化, 响应式, 兼容性
Qt	Qt Guide	对象模型, 信号/槽, 内存管理, 线程安全, 性能

Cross-Cutting Guides

跨领域指南

Language-agnostic patterns applicable to all code reviews:

Topic	Reference File	Key Topics
Universal Quality	Universal Quality Guide	Reuse audit, parameter sprawl, leaky abstractions, nested conditionals, stringly-typed code, TOCTOU, no-op updates, redundant state

适用于所有代码审查的语言无关模式：

主题	参考文档	核心主题
通用质量	Universal Quality Guide	复用性审计, 参数膨胀, 抽象泄漏, 嵌套条件, 字符串类型化代码, TOCTOU, 无操作更新, 冗余状态

Additional Resources

额外资源

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 - 快速参考清单

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 - 快速参考清单