评论语气的定位
评审评论面向代码与事实，而不是作者本人。同一个问题写成「这段在并发写入下会读到脏数据」，和写成「你怎么又写错了」，信息量相同，后果完全不同：前者推动修复，后者让作者先进入防御状态。语气不是礼貌装饰，它决定团队里还有没有人愿意在评审里提异议、承认错误。
基本信息
| 适用平台 | GitHub PR / GitLab MR / Gerrit Change / 邮件评审通用 |
|---|---|
| 目标 | 让问题被修掉，而不是让作者被说服 |
| 判断标准 | 评论里的结论能否只靠事实与依据成立 |
| 常见载体 | 行内评论、PR 总评、Conventional Comments 标签 |
典型使用场景
- 提出阻塞问题：先写触发条件与后果，再给出可验证的修复方向
- 指出风格差异：标明这是个人偏好，交给格式化工具或团队规范处理
- 追问设计取舍：这里不复用 X 是出于什么约束，常能问出真实限制
- 肯定有效部分：改动中解决得好的地方点名说明，讨论才有正反馈
- 给新人反馈：解释规则背后的原因，而不是只丢一个结论过去
句式改写对照
| 场景 | 容易失焦的写法 | 对事的写法 |
|---|---|---|
| 并发错误 | 你这里写错了 | 这段在并发写入下会读到脏数据，建议加锁或改成原子操作 |
| 命名问题 | 名字起得太烂 | 这个变量看不出单位，建议改成 timeoutMs |
| 设计追问 | 为什么不按我说的做 | 这里不用 X 的考虑是什么，是否存在兼容约束 |
| 微小瑕疵 | 这也要我说一遍 | 这是非阻塞建议，可以后续单独处理 |
| 规范不熟 | 连规范都没看过 | 团队规范第三节有说明，链接在此，沿用即可 |
评论结构模板
评论结构模板
1. 现象：哪一行、什么条件下出现。
2. 影响：会导致什么后果，如数据错误、性能退化、兼容性破坏。
3. 依据：团队规范、接口文档或可复现的操作步骤。
4. 建议：给出方向或替代写法，必要时标注为非阻塞。
示例：并发下单次读会返回过期值，对账金额可能算错，
依据接口文档里的幂等要求，建议写入前校验版本号。心理安全感决定评审能不能说真话：把「谁写错了」换成「哪个条件下会出问题」，才有人愿意在合入前主动上报。
把语气问题当小事：长期的对人式评论会让评审变成走过场，作者开始挑评审人说话，缺陷随之流入主干。