Chinese Code Review

中文代码审查规范

概述

国内团队做 Code Review 常遇到两个极端：要么过度客气导致关键问题被放过，要么照搬西方直白风格让同事下不来台。本技能帮你找到平衡点——既不回避问题，又让人愿意接受反馈。

核心原则： 用"建议"代替"命令"，用"提问"代替"否定"，但绝不因为面子而放过 bug。

审查反馈的表达方式

用建议代替命令

避免（命令式）	推荐（建议式）
你必须改成 X	建议考虑用 X，因为 Y
这里写错了	这里可能存在一个问题，是否考虑过 Z 的情况？
不要用这个方法	这个方法在 A 场景下可能有性能问题，可以看看 B 方案
这段代码不行	这段逻辑我理解得对吗？如果输入为空的话会怎样？

用提问代替否定

当你不确定对方意图时，先问再评：

# 好的方式
这里用 sync 方式读文件是出于什么考虑？如果并发量上来，可能会阻塞事件循环。

# 不好的方式
这里不应该用 sync 方式读文件。

分级标注

统一使用优先级标记，让作者快速判断轻重缓急：

• [必须修复] — 安全漏洞、数据丢失风险、逻辑错误（不修不能合）
• [建议修改] — 性能问题、可维护性、缺少校验（本次或下次迭代修复）
• [仅供参考] — 命名优化、风格建议、替代方案（不改也行）
• [问题] — 不确定的地方，需要作者解释意图

审查评论模板

[必须修复] SQL 注入风险

第 42 行：用户输入直接拼接到 SQL 语句中。

原因：攻击者可以通过 name 参数注入 `'; DROP TABLE users; --`。

建议：使用参数化查询：
  db.query('SELECT * FROM users WHERE name = ?', [name])

参考：https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html

中英混排代码注释规范

何时用中文

• 业务逻辑说明 — 用中文解释业务背景和需求来源
• 复杂算法注释 — 用中文写思路，确保团队成员都能理解
• TODO / FIXME — 用中文描述待办事项，方便搜索和追踪
• 文档注释（内部项目） — JSDoc / Javadoc 中的描述文字用中文