Superior Comments 是一个专注于源代码注释维护的技能,适用于注释清理、文档注释整理和 TODO 质量提升等任务。其核心目标是在不触碰可执行代码、导入、配置、生成文件或注释外格式的前提下,让注释真正传递代码无法清晰表达的信息。
用途:用于仅涉及注释的修改工作,包括添加、修订或删除注释,帮助开发者区分哪些注释值得保留、哪些属于噪声。
主要能力:保留解释意图或非显而易见不变量的注释;保留说明为何看似更简单的方案不安全、协议/兼容/安全/法律约束、单位与坐标系统、所有权、生命周期或顺序假设、带足够上下文的工作区变通方案、文档工具消费的公共 API 契约,以及含条件、负责人/引用或具体下一步的可执行 TODO。不轻易删除许可证头、归属说明、生成文件警告、linter 指令、迁移说明或运维指令,除非能证明其已过时。同时识别并移除或重写逐行复述可见语法的注释、装饰性分隔符与空章节标签、宣告工作流程的注释、空泛 TODO、标记生成工作结束的结论或签名、无领域含义的表情或夸张措辞,以及与实现矛盾的陈旧声明。
使用方式:优先为一段连贯逻辑写一条说明原因的注释,而非每条语句一条注释;重复精确的领域术语比不断换同义词更清晰。遵循仓库原有语言、注释语法、文档格式和语气,让注释紧贴其约束的行为。当注释有误但代码仅用于阅读时,应修正注释以描述当前行为,而不是悄悄改代码去迎合注释。完成后检查差异,确认只改动了注释;仅当注释语法可能影响编译、生成文档、指令或工具链时,才运行窄范围的格式化器或解析器。对因无法证伪其运维作用而保留的模糊注释应予以报告。
适用场景:注释专项清理、文档注释维护、TODO 质量改进、代码审查中的注释一致性检查等。
限制:该技能不改变可执行行为,不处理注释以外的代码、格式化、导入或配置;对无法确认是否过时的特殊注释倾向于保留并报告,而非直接删除。