用途:这是一项关于编写“常青注释”的规范技能,核心原则是注释只解释代码当前做什么(WHAT)或为什么存在(WHY),绝不描述它比过去更好或记录变更历史。
主要能力:给出何时使用该规范的场景,包括文件头(ABOUTME 模式)、函数与类文档、复杂逻辑说明、非显而易见的 WHY 推理;尤其在重构、替换实现、改进代码或审查旧注释时使用。规则明确禁止记录变更或历史、禁止写指导性注释、禁止使用“更好/改进”等表述,并强调始终用 ABOUTME 为文件头。
使用方式:每个文件以两行 ABOUTME 头开始,格式为“// ABOUTME: 第一行说明文件用途”“// ABOUTME: 第二行说明关键细节”,可用 grep -r "ABOUTME:" . --include="*.ts" 检索。重构时删除描述旧行为的注释,不新增关于变更的注释;除非注释被证明为假,否则保留仍然准确的注释。提交前按检查清单核对:只讲 WHAT 或 WHY、无时间背景、无旧实现引用、无指导性语言、文件有 ABOUTME 头、保留准确注释、不出现 new/old/improved/refactored 等词。
适用场景:代码重构、实现替换、代码改进、旧注释审查,以及需要统一注释风格的团队。
限制:资料未提供该技能的安装方式、平台支持、收费信息或具体工具集成细节;其内容为写作规范,不涉及自动化执行或代码生成。