用途:为代码补充真正有价值的注释。其核心主张是注释只应说明代码无法表达的内容:如果代码本身就能让读者理解,则不应加注释,而应先改进命名;如果无法理解,则找出缺失的信息并选择对应注释类型。
主要能力:提供一套判断与分类方法。写作前先做“试金石”自检——脱离注释读者能否理解?能则不写,改为改进名称;不能则定位信息缺口。它把信息缺口与注释类型对应:函数契约与副作用对应放在函数/类型顶部的函数注释;为何采用该架构、拒绝过哪些替代方案对应放在文件/包顶部的设计注释;为何这一行这样写而非更自然的写法对应紧贴该行的 Why 注释;读者所需的数学、协议、算法等领域知识对应 Teacher 注释;改动此处还需同步更新什么对应作为警告的内联 Checklist 注释;一段 5 至 20 行代码整体在做什么(认知分块)对应块上方的 Guide 注释。
明确禁止:琐碎注释(如给 i++ 写“递增计数器”)、注释掉的旧代码备份、内联 TODO/FIXME 债务标记。规则要求使用完整句子,解释“为什么”而非“是什么”,优先改好命名;在结构体/API 上注释可多于代码,需记录字段生命周期(谁初始化、谁修改、何时失效);若评审者提出疑问,就应补上注释,因为下一位读者会有同样疑问。
自检:写完先只读注释,看它能否作为关于系统的独立陈述成立;再只读代码,看是否还有非显而易见之处未被解释。
适用场景:为代码添加或审查注释、回答如何写出好注释。使用方式与安装命令:资料未提供。平台、收费与价格信息:暂未提供。