antislop-code 是 antislop 系统的一部分,属于“代码注释”技能。它需要与核心文件 antislop.md 一起阅读和使用。当任务涉及编写或编辑代码注释时,应加载本技能。核心文件包含机制(目的测试、三个层级、交付门),本技能则提供注释相关的具体深度规则。每条规则都引用核心规则编号,不重复或重新编号。
使用方式
每当任务触及代码注释时,将本技能与 antislop.md 一起加载。每条规则结构一致:Tell(模式)、Why(为何读起来像 AI 垃圾)、Fix(应如何处理),并引用核心规则 R-XX。
范围护栏:本技能只修改注释。绝不修改可执行代码、标识符、导入、格式、缩进、空白、控制流或逻辑。如有疑问,保持代码不动。核心中的交付门仍然是最终关卡,本文件末尾的“代码注释检查清单”是注释层面的补充。
不增加信息的注释
装饰性分隔符
Tell:由重复字符构成的横幅注释、全大写标签或围绕区块名称的框线,例如 // ======================= 围绕 Authentication,// -------- WORKFLOW --------,或 /* ---- ROUTES ---- */ 标题。 Why:装饰本身就是信息。用 = 或 - 包裹的标签暗示“这是 AI 做的”,却不增加信息,全大写读起来像在喊叫。 Fix:替换为单行普通文本,如果标签没有增加任何内容则完全删除(R-31)。
重复显而易见的内容
Tell:注释重复下一行或声明已经显示的内容,例如 // Initialize the variable 在 let count = 0 上方,// User class 在 class User {} 上方,// Validate user 在 function validateUser() 上方,或 const userAge = 25; // User age is 25. Why:它加倍了阅读负担却不增加任何内容。代码已经说了,注释只是重复。 Fix:删除,保持代码行不动。
工作流叙述
Tell:逐步叙述流程的注释,例如 // Step 1: Validate input,// Step 2: Process request,// Step 3: Return response,或 // First...,// Next...,// Finally...。 Why:控制流在代码中已经可见。编号读起来像清单,而不是解释。 Fix:删除。如果流程确实难以理解,那是结构问题,不是缺少注释的问题。
空标签
Tell:没有信息支撑的通用标签:// Main logic,// Core logic,// Business logic,// Helper function,// Entry point,// Error handling,或 // Note: This is important. / // Important: Please read. Why:标签命名的是类别,不是事实。“Main logic”没有告诉读者任何无法从代码推断的内容。 Fix:除非标签携带具体信息,否则删除。“Note: retries happen only on 5xx”值得保留;“Note: this is important”不值得。
模糊占位符
Tell:承诺未来工作但不说明具体内容的注释:// TODO: Improve this,// Future improvements,// Additional optimization can be added here,// Add more validation。 Why:模糊的 TODO 是噪音。它命名的是感觉(这可以更好),而不是任务(做什么,为什么)。 Fix:删除。只有当 TODO 命名了具体任务并有足够上下文可执行时才保留。
签名回声
Tell:只重复签名的文档,例如 JSDoc 块重复 @param price The price. 和 @returns Total price.,而函数名和参数已经说明了一切。 Why:回声签名的文档增加长度,不增加理解。读者学不到新东西。 Fix:简化或删除回声。保留解释业务规则、边界情况、假设、算法、限制、副作用、API 行为或安全影响的文档。绝不剥离真正的文档。
装饰性表情符号
Tell:注释中用作装饰的表情符号,例如 // ✅ Validation 或 // 🚀 Performance。 Why:表情符号在代码中是视觉噪音,而且特定集合(✅、🚀、🔒)是 AI 的默认词汇。 Fix:替换为普通英文,如果标签没有增加内容则删除。
结束标记
Tell:只标记块结束的注释,例如 } // end if,# End of function,或 // End processOrder。 Why:闭合大括号已经结束了块。标记是出于习惯,不是需要。 Fix:删除。在极少数情况下,结束标记确实有助于长文件,只在能防止混淆的地方保留,而不是作为习惯。
应该如何书写
过度解释的注释
Tell:一条注释延续数行,围绕一个一行就能容纳的事实堆叠原因、上下文和历史:一个四行块解释一个 stub 位于 PATH 上、哪个版本引入了这个变通方法、之前什么坏了。每句话都是真的。长度就是信号。 Why:人留下的是便条,生成器写的是案例。把一行事实填充成一段,构建“因为 X,所以 Y,因此 Z”的链条,或引用问题编号和修复版本,都是与其他 AI 模式相同的花招,它们把重要的那一行埋在不重要的行下面。 Fix:削减到只保留约束:一行,最多两行,绝不超过三行。保留平台陷阱、静默失败、协议规则、性能成本。去掉问题编号、版本历史和推理链。
逐行叙述
Tell:对每个琐碎语句都加注释,逐行叙述:// Initialize count,然后 // Loop items,然后 // Get item,然后 // Increment,然后 // Return result。 Why:当每一行都有注释时,没有一条注释重要。读者必须检查每一条才能找到有意义的那条。 Fix:每个逻辑块写一条简洁注释,而不是每行一条。如果块不需要注释,就不写。
生硬或喧哗的措辞
Tell:听起来正式、冗长或喊叫的注释:“This function is responsible for validating whether the supplied credentials are valid before continuing with the authentication process”,或 // MAIN LOGIC 全大写。 Why:正式和喧哗的措辞读起来像生成的,而不是工程师给下一个人留的便条。 Fix:用自然的开发者语气写简短的句子大小写行:// Validate credentials before issuing a token. 好的注释解释为什么,而不是什么,并且保持简短。
不是禁令(保留这些)
绝不删除解释以下内容的注释:
业务逻辑和意图
架构决策
安全考虑
性能权衡
并发行为
协议细节
API 契约
变通方法
边界情况和假设
许可和法律声明
必须保留的示例:
// Stripe may retry webhook deliveries for up to three days. // Ignore duplicate events using the event ID.
当注释解释了代码没有显示的内容时,它就值得保留:原因、约束、非显而易见的行为。
值得保留说明什么可以留下,绝不说明可以写多长。变通方法注释是一行关于变通方法的内容,不是一段。上面的示例是两行,因为两个事实是真实的,不是因为两行是目标。这个清单是注释在审查中不该存活却存活的最常见原因:内容确实有价值,所以长度未被审视。价值不等于长度。
代码注释检查清单
当任务触及注释时,与核心交付门一起运行这些检查。所有答案必须为“是”:
每条注释是否都增加了代码未显示的信息?(R-31)
注释是否避免了装饰性分隔符、全大写横幅和框线标题?
注释是否避免了重复显而易见的行、声明或签名?
注释是否避免了逐步工作流叙述?
注释是否避免了空标签和不命名任务的模糊 TODO?
注释是否避免了装饰性表情符号和结束标记?
注释密度是否为每个逻辑块一条,而不是每行一条?
每条注释是否只有一行,或仅当第二行携带新事实时才为两行?
剩余注释是否读起来简短、自然、句子大小写?
范围护栏是否守住:只改注释,代码未动?