conventional-comments

Conventional Comments

基于 Conventional Comments 标准。让评论易于理解和检索。

评论格式

<label> [decorations]: <subject>

[discussion]

• label（必填）——表示评论类型的单个单词
• subject（必填）——评论的主要内容
• decorations（可选）——括号中的额外分类标签，以逗号分隔，放在 label 后面
• discussion（可选）——补充说明、背景、理由和后续步骤

标签

使用以下标签为每条评论加前缀：

Label	用途
praise	指出值得肯定之处。每次评审至少留一条。必须真诚——虚假的赞扬会带来负面影响。
nitpick	基于偏好的细枝末节建议。原则上不影响通过。
suggestion	提出改进建议。明确说明改什么以及为什么。
issue	指出具体问题（面向用户或内部）。尽可能配上建议。
todo	小而琐碎但必须完成的改动。比 issue 或 suggestion 更简单。
question	你不确定是否存在的潜在问题。请求澄清或调查。
thought	评审过程中想到的点子。不会阻碍通过，但有助于指导和聚焦改进。
chore	验收前必须完成的任务。尽可能链接到流程说明。
note	始终不阻碍通过。提醒读者注意某件事。

可选的表达性标签：

Label	用途
typo	类似 todo，但针对拼写错误。
polish	类似 suggestion，但没有错误——只是可以立即提升质量。
quibble	类似 nitpick，但不带比喻意味。

装饰标签

装饰标签用于在 label 后面的括号中补充背景：

Decoration	含义
(non-blocking)	不应阻碍验收。当评论默认会阻碍验收时很有用。
(blocking)	必须在验收前解决。当评论默认不会阻碍验收时很有用。
(if-minor)	仅当修复较小或琐碎时才解决。

可以添加自定义装饰标签（例如 security、ux、test、performance），进一步分类评论。尽量保持精简——装饰标签过多会影响可读性。

代码评审格式

所有评论输出都必须是有效的 GitHub 风格 Markdown——假设内容会被复制粘贴到 PR 评论中。

代码引用

只有在指向评论所在位置以外的位置时，才明确写出文件路径或行号（例如，相关代码位于其他文件、共享工具，或需要更新的测试）；否则，GitHub 的评审界面会处理评论定位。

评论中的代码

• 行内代码（变量名、函数调用、值）用单个反引号括起来：`myFunction()`
• 多行代码片段使用带语言标签的围栏代码块：

```python
def example():
    return True
```

• 建议替换代码时，使用围栏代码块同时展示当前代码和建议代码

沟通最佳实践

保持好奇

假设自己掌握的背景信息并不完整。提出问题，而不是将结论当作事实陈述。

• 不佳：在 Main 组件中解决这个 bug 可能会少写很多代码。
• 良好：question：“我们能否在 Main 组件中解决这个问题？我想知道这样是否会更直接，也能减少代码量。”

用“我们”代替“你”

书面评审缺少口语语气。写“你应该”会让人觉得是在针对对方；“我们应该”则更有协作感。

• 不佳：issue：“你应该为此编写测试。”
• 良好：todo：“我们应该为此编写测试。”

留下可执行的评论

明确说明应如何解决评论指出的问题。如果没有明确的解决路径，也要说明这一点。

合并相似评论

将相似问题合并到一条评论中，而不是拆成多条零散评论。适当时附上补丁或示例。

耐心指导

以耐心和善意分享的知识会更深入人心，并惠及未来的评审。

示例

赞扬：

praise: 测试覆盖做得非常出色，边缘情况也考虑得很周全。

附带代码的建议：

suggestion (security): 我有些担心我们在这里自行实现 DOM 清理函数。

我们能否考虑改用框架内置的清理器？

// Instead of
function sanitize(input: string) { ... }

// Use
import { sanitize } from '@angular/core';

带有修饰说明的问题：

issue (ux, non-blocking): 这些按钮应该是红色的，不过我们可以在后续处理中解决。

带有修饰说明的问题：

question (non-blocking): 到这里，哪个线程胜出重要吗？

或许为了避免竞态条件，我们应该持续循环，直到它们全部胜出？

吹毛求疵：

nitpick: little star => little bat

我们能把其他引用也一并更新吗？

跨文件引用（指向其他位置时）：

suggestion: 这段验证逻辑与 src/utils/validate.ts#L30-L45 中的逻辑重复了。我们能否改为在这里复用 validateInput()？

杂务：

chore: 我们运行一下 lint-check CI 作业，确保这不会破坏任何已知引用。

这是运行此作业的文档。如果需要帮助，请随时联系我！

组合建议（合并相似反馈）：

polish: 我们能否将所有 m_X 变量都重命名为 X？这个项目并未遵循匈牙利命名法。

例如：

// Instead of
interface Wizard { m_foo: string; }

// Use
interface Wizard { foo: string; }