用途
本技能面向国内团队的 Code Review 场景,解决两个常见极端:过度客气导致关键问题被放过,或照搬西方直白风格让同事下不来台。目标是在不回避问题的前提下,让反馈更容易被接受。
核心原则:用「建议」代替「命令」,用「提问」代替「否定」,但绝不因为面子而放过 bug。
主要能力
审查反馈的表达方式
用建议代替命令,例如把「你必须改成 X」改为「建议考虑用 X,因为 Y」;把「这里写错了」改为「这里可能存在一个问题,是否考虑过 Z 的情况?」。
用提问代替否定,当不确定对方意图时先问再评。例如:「这里用 sync 方式读文件是出于什么考虑?如果并发量上来,可能会阻塞事件循环。」
分级标注
统一使用优先级标记,让作者快速判断轻重缓急:
- [必须修复] — 安全漏洞、数据丢失风险、逻辑错误(不修不能合)
- [建议修改] — 性能问题、可维护性、缺少校验(本次或下次迭代修复)
- [仅供参考] — 命名优化、风格建议、替代方案(不改也行)
- [问题] — 不确定的地方,需要作者解释意图
审查评论模板
以 SQL 注入风险为例,模板包含:问题定位(第 42 行)、原因说明(攻击者可注入 '; DROP TABLE users; --)、修复建议(使用参数化查询 db.query('SELECT * FROM users WHERE name = $1', [name]))以及参考链接。
中英混排代码注释规范
何时用中文:业务逻辑说明、复杂算法注释、TODO / FIXME、内部项目的文档注释(JSDoc / Javadoc 描述文字)。
何时用英文:变量名、函数名、类名;Git commit message;开源项目注释;生产环境错误信息和日志;对外 API 接口文档。
混排格式要求:中英文之间加空格;技术术语保留英文,不强行翻译。
Commit Message 中英双语格式
团队内部项目推荐使用约定式提交(Conventional Commits)的中文版,格式为 <类型>(<范围>): <简要描述>,并附详细说明与关联信息。类型对照表包括 feat、fix、docs、style、refactor、perf、test、chore。面向国际社区的项目使用英文 commit message,PR 描述中可附加中文说明。
常见反模式与对策
- 过度客气:关键 bug 被委婉语掩盖。对策是使用分级标注,语气可温和但级别必须准确。
- 不敢给高级开发者提意见:导致代码质量双标。对策是对事不对人,可用提问式或学习式表达。
- 审查变成风格之争:浪费时间。对策是风格问题交给 ESLint / Prettier / gofmt 等工具自动处理。
- 只写「LGTM」:审查形同虚设。对策是即使代码质量好,也要写出关注了哪些方面。
审查流程建议
开始审查前先看 PR 描述和关联 Issue,先整体浏览再逐文件细看。审查顺序为:架构层面、正确性、安全性、性能、可维护性、风格。审查结束后给出总结,包括整体评价、值得学习的地方、主要问题列表(按优先级)和建议的修改方向。
检查清单
提交审查意见前确认:每条评论都标注了优先级;[必须修复] 的问题都给出了具体修复建议;没有因面子跳过关键问题;没有纠结于工具能自动处理的风格问题;对好的代码给予了肯定;给出了整体总结。
使用方式
本技能以规范文档形式提供,可在进行 Code Review 时参照其中的表达方式、分级标注、评论模板、注释规范、Commit 格式、反模式对策、流程建议和检查清单执行。具体安装命令与集成方式暂未提供。
适用场景
适用于国内开发团队的代码审查、Pull Request 评审、代码注释与 Commit Message 规范制定等场景,尤其适合需要兼顾专业严谨与团队沟通文化的团队。
限制
本技能为规范与话术指南,不包含自动化审查工具或代码检查功能。具体工具集成方式、平台支持范围暂未提供。