name: comment-cleanup description: “清理代码注释。使用场景：提升注释质量，移除冗余注释。触发条件：‘清理注释’、‘注释清理’。” allowed-tools: Read, Edit, Glob, Grep disable-model-invocation: true argument-hint: <文件路径>
注释清理
我将遵循战略性文档原则，分析并改进指定文件中的文档。
目标文件
$ARGUMENTS
文档哲学
核心原则
- 代码自文档化优先 - 在添加注释前，先改进命名和结构
- 注释捕获设计意图 - 记录“为什么”，而不是“是什么”（当“是什么”显而易见时）
- 减少认知负荷 - 将隐含知识显式化
- 消除冗余 - 绝不重复代码已清晰表达的内容
什么是好的注释
- 设计决策 - 为什么选择这种方法而非其他替代方案
- 非显而易见的行为 - 不立即清晰的复杂逻辑
- 接口契约 - 函数/模块的功能、参数、返回值
- 重要上下文 - 理解所需背景信息
- 陷阱与边界情况 - 可能导致问题的微妙行为
- 依赖关系 - 组件之间如何关联
应避免的注释
- 重复陈述明显代码的冗余注释
- 重复命名良好的变量/函数的注释
- 自明的实现细节
- 容易过时的注释
分析流程
- 阅读文件以理解其目的和结构
- 识别命名改进，使代码更具自文档性
- 查找需要解释的复杂逻辑
- 定位应记录的设计决策
- 移除有害注释，即增加噪音或已过时的注释
- 在能减少认知负荷的地方添加战略性注释
执行
我将：
- 首先阅读并分析目标文件
- 如有需要，建议并应用命名改进
- 移除冗余或误导性注释
- 仅在以下情况添加注释：
- 解释非显而易见的行为
- 记录设计决策
- 阐明复杂算法
- 提供必要的接口文档
- 确保所有更改遵循“营地规则”——让代码比发现时更整洁
目标是最小化、高价值的文档——让代码足够清晰，几乎不需要注释，然后仅在注释能捕获代码无法表达的必要信息时才添加。