用途:该技能是仓库代码注释规范的入口,适用于新增、编辑、审查注释,或判断是否保留、删除注释,以及决定注释位置和官方文档 URL 的写法时使用。
主要能力:将注释内容限定为 Why not(为何不采用其他方案、为何不能简化或删除)及判断依据;避免在注释中写正面采用理由(由 commit log 承担);要求保留参考的官方文档 URL;区分面向整个文件的注释与局部注释的放置方式;避免注释变成对 What(处理内容)或 How(实现步骤)的说明。
使用方式:先阅读 references/why-not.md,了解 Why not 的判定标准、判断步骤与示例;再阅读 references/official-doc-url.md,了解官方文档 URL 的处理与放置规则及示例;必要时结合周边代码与相关文档。最后按检查项核对:注释是否解释 Why not、是否误写 positive Why、是否保留官方文档 URL、文件级与局部注释位置是否分开、是否落入 What/How 说明。
适用场景:仓库内代码注释的日常维护与评审。
限制:资料未提供具体安装命令、平台支持、收费方式或效果数据;详细规则需查阅上述两个 references 文件。