Code Review

---
name: code-review
description: >
  评审代码，不评审人：给可操作建议、提问而非命令、解释为什么、区分阻断与建议、肯定好的做法、知道何时收手。
  Use when the user asks to review a PR, diff, or code change, or wants review feedback
  improved or responded to. 触发于「帮我评审这段代码/这个 PR」「回复 review 意见」。
---

# 代码评审

主线：评审是异步地「谈论代码」——有人提出改动，其他人思考它、像头脑风暴一样讨论好在哪、坏在哪。它关乎**这段代码在此项目、此目的、此刻是否合理**，与写代码的人无关。评审不是官僚负担：它在代码入库前抓 bug、在团队内传播知识，也是最快的学习方式之一——既能看到要避免的错误，也能学到好模式。新鲜眼睛能抓到资深开发者忽视的东西。commit 拆分质量（`git add -p`）是评审的常规检查项，标准见 `writing-for-readers`。

## 给出评审

- **评审代码，不评审人**：「这个函数读起来费解」而非「你写的代码很难懂」。评审体验决定贡献者是否愿意回来——每次开口都是挑错，没人想再来第二次。
- **给可操作的建议**：「这里能否改用配置 dataclass，而不是全局变量？这样测试可以并行跑」而非「别用全局变量」。
- **提问而非命令**：「如果这里 X 为 null 会怎样？」而非「把 null 情况处理掉」——促进讨论，也让对方自己意识到问题。
- **解释为什么**：「这里用常量吧」不如「用常量，方便按环境调整超时时间」。
- **区分阻断性问题与建议**：说明哪些必须修改、哪些只是偏好；非阻断的按惯例标 `nit:`，让对方能按优先级分诊。
- **评论别泛滥**：一百条评论里，可能一半在头五十条改完后已经失效；对方也不知道哪条最重要。重复出现的模式只评第一处：「这是本仓库的变量命名规范，请在全代码库统一使用」，而不是逐行炮轰。
- **肯定做得好的地方**：指出巧妙的解法或干净的实现——结对编程时如果每次开口都是说对方做错了，那会是很糟的体验，评审同理。它让评审更平衡，也让对方更有动力改你要求的部分。
- **知道何时收手**：盯住大问题，小问题必要时自己事后顺手清理。
- **AI 只能做第一道筛查，不能替代人工评审**：LLM 做的是 zero-context review——只看 diff 和描述。而评审真正重要的部分（这个改动对整体代码库、产品方向、版本策略是否是好主意？是不是还没准备好发 breaking change？）恰恰需要它没有的上下文；给它塞上下文也常常只是复述模式而非真正理解。AI 说没问题 ≠ 维护者会同意。

## 收到评审

- **「代码不是你本人」**：审核者是在让代码更好，不是批评你。
- 不同意就提澄清问题——也许你能学到东西，或者他们能学到。

## 练习

学习材料在 `exercises.md`。

> 改编自 MIT The Missing Semester 课程 Lecture 8: Beyond the Code（讲义 + 口播稿，CC BY-NC-SA 4.0）：https://creativecommons.org/licenses/by-nc-sa/4.0/ · 课程站点：https://missing.csail.mit.edu/ · 讲座视频：https://www.youtube.com/watch?v=2DOEATfXT8k