superior-comments

优质注释

让注释传达代码无法清晰表达的信息。在仅修改注释的任务中，不要更改可执行代码、注释以外的格式、导入、配置或生成文件。

保留有解释作用的注释

• 说明意图或不明显的不变量；
• 解释为什么看似更简单的做法并不安全；
• 说明协议、兼容性、安全或法律约束；
• 说明单位、坐标系、所有权、生命周期或顺序假设；
• 说明变通方案，并提供足够背景以便安全移除；
• 说明文档工具会读取的公共 API 契约；
• 说明可执行的 TODO，并在可行时注明条件、负责人或参考信息，或具体的后续步骤。

除非能证明其已过时，否则不要删除许可证头、署名、生成文件警告、代码检查指令、迁移说明或操作指南。

删除或改写噪声

• 对显而易见语法逐行进行的叙述；
• 装饰性分隔符和空白小节标题；
• 宣告 Agent 工作流程的注释；
• “以后再改进”之类含糊的 TODO；
• 标记生成工作结束位置的结论或签名；
• 不包含领域含义的表情符号或夸张措辞；
• 与实现相矛盾的过时说法。

对于一段连贯代码块背后的原因，优先用一条注释说明，而不是每条语句都写一条注释。重复使用准确的领域术语，比换用同义词更清晰。

与代码库保持一致

保留仓库使用的语言、注释语法、文档格式和常见语气。注释应靠近其约束的行为。如果注释有误，但当前任务只允许阅读代码，则应修正注释以描述当前行为；不要暗中更改行为来迎合注释。

验证

检查差异，并确认只有注释发生了变化。只有当注释语法可能影响编译、生成文档、指令或工具时，才运行范围较窄的格式化工具或解析器。如果保留了某条含义不明的注释，因为无法证明它不再具有操作作用，请说明这一点。