chinese-code-review

1# 中文代码审查规范
2 
3## 概述
4 
5国内团队做 Code Review 常遇到两个极端：要么过度客气导致关键问题被放过，要么照搬西方直白风格让同事下不来台。本技能帮你找到平衡点——**既不回避问题，又让人愿意接受反馈**。
6 
7**核心原则：** 用"建议"代替"命令"，用"提问"代替"否定"，但绝不因为面子而放过 bug。
8 
9## 审查反馈的表达方式
10 
11### 用建议代替命令
12 
13| 避免（命令式） | 推荐（建议式） |
14|---------------|---------------|
15| 你必须改成 X | 建议考虑用 X，因为 Y |
16| 这里写错了 | 这里可能存在一个问题，是否考虑过 Z 的情况？ |
17| 不要用这个方法 | 这个方法在 A 场景下可能有性能问题，可以看看 B 方案 |
18| 这段代码不行 | 这段逻辑我理解得对吗？如果输入为空的话会怎样？ |
19 
20### 用提问代替否定
21 
22当你不确定对方意图时，先问再评：
23 
24```
25# 好的方式
26这里用 sync 方式读文件是出于什么考虑？如果并发量上来，可能会阻塞事件循环。
27 
28# 不好的方式
29这里不应该用 sync 方式读文件。
30```
31 
32### 分级标注
33 
34统一使用优先级标记，让作者快速判断轻重缓急：
35 
36- **[必须修复]** — 安全漏洞、数据丢失风险、逻辑错误（不修不能合）
37- **[建议修改]** — 性能问题、可维护性、缺少校验（本次或下次迭代修复）
38- **[仅供参考]** — 命名优化、风格建议、替代方案（不改也行）
39- **[问题]** — 不确定的地方，需要作者解释意图
40 
41### 审查评论模板
42 
43```
44[必须修复] SQL 注入风险
45 
46第 42 行：用户输入直接拼接到 SQL 语句中。
47 
48原因：攻击者可以通过 name 参数注入 `'; DROP TABLE users; --`。
49 
50建议：使用参数化查询：
51  db.query('SELECT * FROM users WHERE name = ?', [name])
52 
53参考：https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html
54```
55 
56## 中英混排代码注释规范
57 
58### 何时用中文
59 
60- **业务逻辑说明** — 用中文解释业务背景和需求来源
61- **复杂算法注释** — 用中文写思路，确保团队成员都能理解
62- **TODO / FIXME** — 用中文描述待办事项，方便搜索和追踪
63- **文档注释（内部项目）** — JSDoc / Javadoc 中的描述文字用中文
64 
65```typescript
66/**
67 * 计算用户的会员等级折扣
68 *
69 * 业务规则：
70 * - 普通会员 9.5 折
71 * - 银卡会员 9 折
72 * - 金卡会员 8.5 折
73 * - 钻石会员 8 折
74 *
75 * @param level - 会员等级（MemberLevel enum）
76 * @param amount - 原始金额（单位：分）
77 * @returns 折后金额（单位：分）
78 */
79function calculateDiscount(level: MemberLevel, amount: number): number {
80  // ...
81}
82```
83 
84### 何时用英文
85 
86- **变量名、函数名、类名** — 始终用英文命名，遵循团队命名规范
87…