code-comments

代码注释

编写有效注释的指南：说明意图，同时避免代码杂乱。

适用场景

• 添加注释来解释不明显的代码
• 检查现有注释是否清晰、准确
• 判断代码是否需要注释，或是否应该改为重构

不适用于： 特定语言的文档语法（JSDoc、文档字符串、Go 文档注释）、文档生成或提交消息。

流程

1. 判断是否需要注释 — 尽可能让代码自我说明。以下情况值得添加注释：

   • 代码没有明显说明原因
   • 存在不明显的决策或限制
   • 需要说明边界情况或变通方案
   • 需要标记未来工作或已知限制（TODO/FIXME）

2. 编写简洁、准确的注释 — 每个词都应发挥作用：

   • 优先使用单行注释；遵循现有约定和 lint 规则
   • 每个注释块最多三行
   • 说明意图或限制，而不是代码的作用
   • 使用完整的表达，不要写需要反复阅读才能理解的片段

3. 合理放置注释 — 位置很重要：

   • 将注释放在所说明代码的上方，而不是行内（解释特定代码行时除外）
   • 注释应靠近所说明的代码
   • 避免使用导致代码向右延伸过远的行尾注释

4. 保持注释与代码同步 — 过时注释比没有注释更糟：

   • 代码变更时更新注释
   • 删除不再适用的注释
   • 切勿在没有说明的情况下留下已注释掉的代码

应添加注释的内容

• 说明原因，而非内容： 解释理由，而不是机制
• 不明显的决策： 变通方案、性能选择、兼容性限制
• 边界情况： 边界条件、错误处理的理由
• TODO/FIXME： 附带背景信息的已知限制或未来工作

不应添加注释的内容

• 显而易见的代码： 在 counter++ 上方写 // increment counter
• 已注释掉的代码： 删除它；git 历史会保留记录
• 重复说明： 不要复述代码已清楚表达的内容
• 噪音： 分隔线、装饰性注释、作者标签（使用 git blame）

常见问题

• 过度注释： 复述代码的注释会增加噪音，却没有价值。如果需要解释代码的作用，可以考虑重构。
• 过时注释： 与代码不符的注释会误导后续读者。更改代码时，务必更新或删除注释。
• 已注释掉的代码： 注释中的死代码会让文件杂乱。相信版本控制会保留历史记录。
• 含糊的注释： 没有背景信息的“TODO: fix this”毫无用处。请说明需要修复什么，以及原因。
• 过长的注释： 如果注释超过三行，代码可能需要重构，或者说明内容应该放入文档。

验证

添加或检查注释后，请确认：

• 每条注释都说明原因，而不是内容
• 注释简洁（优先单行，最多三行）
• 没有遗留缺乏理由说明的已注释代码
• 注释与当前代码行为一致
• 显而易见的代码没有多余注释

快速检查清单：

Does this comment explain why, not what?
Is it as short as possible without losing accuracy?
Does it fit in one line (or three at most)?
Is the comment still accurate?
Could the code be clearer instead of needing this comment?