Conventional Comments 是什么
Conventional Comments 是一套给评审评论加标签的约定：用 praise、nitpick、suggestion、issue、todo、question、thought 等词开头，让作者一眼看出这条意见的类型与紧急程度。它解决的是同一句话在不同人眼里严重性不同的问题——标签把「这是我的偏好」与「这里确实有缺陷」区分开。
基本信息
| 形式 | 标签开头，可加修饰词，正文写问题与建议 |
|---|---|
| 常用标签 | praise、nitpick、suggestion、issue、todo、question、thought |
| 修饰词 | non-blocking 标出不阻塞合并，blocking 标出必须处理 |
| 适用场景 | 团队评审、开源项目协作、跨团队异步评审 |
常用标签与含义
| 标签 | 含义 | 典型处理 |
|---|---|---|
| praise | 肯定做法 | 无需行动 |
| nitpick | 小问题（不阻塞） | 可改可不改 |
| suggestion | 建议性改进 | 作者判断 |
| issue | 明确问题 | 应处理 |
| todo | 小任务 | 计划内处理 |
| question | 疑问或澄清 | 需要回答 |
| thought | 引出讨论的想法 | 视讨论结果 |
格式示例
格式示例
suggestion (non-blocking): 这里可以复用已有的重试装饰器，减少重复逻辑。
issue: 并发场景下这个读取没有加锁，可能读到半更新状态。
question: 这里保留旧参数是为了兼容哪个调用方？
todo (if-minor): 顺手补一下这个分支的日志，方便线上排查。使用规矩
- 标签与内容必须一致：标 nitpick 却提阻塞性问题，会误导作者排序。
- 修饰词写清楚：non-blocking 表示可以带着合入，blocking 表示必须先改。
- 同一类意见集中给出：一口气提十个 issue，作者反而不知道该先做哪个。
- 肯定也要说：praise 让作者知道哪些做法值得保留，比只提问题更有用。
- 修饰词随情况变化：同一类建议在关键路径上是 blocking，在边角代码上可以是 non-blocking。
- 标签用在整条评论的开头：夹在句子中间会让人看不出这是标签还是正文。
- 标签不替代理由：说清问题与建议，标签只负责标注类型与紧急度。
标签可配修饰词：blocking 与 non-blocking 标出阻塞性，减少来回确认。
标签是约定不是平台功能：团队需要在使用前说清每个词在本团队的含义。