评论要写清什么

Google 的评论写作指南要求一条评审评论说清三件事：问题是什么、原因或影响是什么、建议怎么改（或者提出一个具体问题）。只给结论的评论会把背景藏起来，作者只能反复追问，评审轮次因此变多；写清为什么的评论还能被后来人读懂，成为代码历史的注解。

基本信息

反例与正例对比

# 反例：只有结论
这里不要这么写。

# 反例：把个人偏好说成规则
我不喜欢这种命名，改掉。

# 正例：问题 + 影响 + 建议
两次查询之间没有事务，并发下可能读到不一致状态；
能不能合并成一次查询，或者用事务把两次读包起来？

# 正例：提问代替命令（作者可能掌握更多上下文）
这里不处理 null 是有意的吗？如果是漏了，建议加一次早返回。

写作要点

• 先写观察到的事实，再给判断：事实可核对，判断可讨论。
• 说明影响：会出错、难以维护、性能退化，用具体后果代替「不好」。
• 给出方向而非命令：建议、提问、示例都可以，作者更容易接受。
• 一条评论只谈一件事：混在一起作者容易漏改，讨论线索也会分叉。
• 不确定意图时先用提问确认，确认后再给结论，避免误判。
• 标出优先级：必须改的与可选的分别标注，降低来回确认成本。

不同类型评论的写法

常见表达的改写

• 「这样不好」→ 说清哪里不好、在什么条件下会出问题。
• 「按规范改」→ 引用具体条款或贴出示例，只提规范名等于让作者去猜。
• 「重写吧」→ 指出结构问题与拆分方向，给一个可执行的起点。
• 「随便」不要写：要么明确标为非阻塞，要么干脆不提。

把意见写得可执行

• 先说清触发条件：什么输入、什么时序下会出问题，作者才能复现。
• 描述你期望的行为：只说不合适没有用，说明改成什么样子才算好。
• 附上依据：团队规范条款、接口约定、性能数据或已有的先例。
• 区分本次必须改与以后再说：前者列为阻塞项，后者标注为后续改进。
• 提问时给出自己的猜测：说明你担心什么，作者的回答会更聚焦。
• 涉及取舍时列出可选方案：把选项讲清楚，作者更容易下结论。