antislop-code

antislop-code

Anti Slop：面向 AI 编码 Agent 的规则。代码注释技能

antislop 系统的一部分。请与核心文件 antislop.md 一起阅读。这项技能会过滤读起来像泛泛 AI 生成的注释（装饰性、重复显而易见的内容、生硬、夸张），同时保留承载真实信息的注释。它通过编号引用核心规则，绝不重复或重新编号。任务涉及编写或编辑代码注释时，请加载此技能。

如何使用此技能

• 任务涉及代码注释时，请始终与 antislop.md 一起加载。核心文件包含机制（目的测试、三个层级、交付关卡）；此技能则深入说明注释相关内容。
• 每条目结构相同：识别（模式）、原因（为何读起来像 AI 垃圾内容）、修正（应该怎么做），并引用适用的核心规则 R-XX。
• **范围护栏：**此技能只修改注释。绝不修改可执行代码、标识符、导入项、格式、缩进、空白字符、控制流或逻辑。如有疑问，请保持代码原样。
• 核心文件中的交付关卡仍是最终关卡。本文件末尾的“代码注释检查清单”是注释专用补充，应与其一并执行。

毫无价值的注释

装饰性分隔线

• **识别：**由重复字符构成的横幅注释、全大写标签，或围绕章节名称的框线，例如围绕 Authentication 的 // =======================、// -------- WORKFLOW --------，或 /* ---- ROUTES ---- */ 标题。
• **原因：**装饰本身就是全部信息。用 = 或 - 包裹标签，会让人觉得“这是 AI 写的”，却没有增加信息；全大写读起来像在大喊。
• **修正：**改成一行普通注释；如果标签没有任何价值，就彻底删除（R-31）。

重述显而易见的内容

• **识别：**注释重复下一行代码或声明已经表达的内容，例如 let count = 0 上方的 // Initialize the variable、class User {} 上方的 // User class、function validateUser() 上方的 // Validate user，或 const userAge = 25; // User age is 25。
• **原因：**这会增加阅读负担，却没有带来任何信息。代码已经说明了内容；注释只是在重复。
• **修正：**删除注释，保留代码行不变。

叙述工作流

• **识别：**逐步叙述流程的注释，例如 // Step 1: Validate input、// Step 2: Process request、// Step 3: Return response，或 // First...、// Next...、// Finally...。
• **原因：**控制流在代码中清晰可见。给步骤编号读起来像清单，而不是解释。
• **修正：**删除。如果流程确实难以理解，那是结构问题，不是缺少注释的问题。

空洞标签

• **识别：**没有提供任何信息的通用标签：// Main logic、// Core logic、// Business logic、// Helper function、// Entry point、// Error handling，或 // Note: This is important. / // Important: Please read.
• **原因：**标签只点出了类别，没有说明事实。“Main logic” 没有告诉读者任何无法从代码中推断出的内容。
• **修正：**除非标签承载具体信息，否则请删除。“Note: retries happen only on 5xx” 有保留价值；“Note: this is important” 则没有。

含糊的占位内容

• **识别：**只承诺未来会改进，却没说明具体要做什么的注释：// TODO: Improve this、// Future improvements、// Additional optimization can be added here、// Add more validation。
• **原因：**含糊的 TODO 是噪声。它描述了一种感觉（这里可以更好），而不是一项任务（做什么，以及为什么）。
• **修正：**删除。只有当 TODO 指明具体任务，并提供足够的背景信息以便着手处理时，才予以保留。

签名复述

• 表现： 文档只是在复述签名，例如，JSDoc 块对一个名称和参数已经说明一切的函数重复写着 @param price The price. 和 @returns Total price.。
• 原因： 复述签名的文档只增加篇幅，并不会增进理解。读者学不到新内容。
• 改进： 精简或删除重复内容。保留解释业务规则、边界情况、假设、算法、限制、副作用、API 行为或安全影响的文档。切勿删掉真正有用的文档。

装饰性表情符号

• 表现： 在注释中用表情符号装饰，例如 // ✅ Validation 或 // 🚀 Performance。
• 原因： 表情符号会给代码带来视觉噪声，而这类特定表情符号（✅、🚀、🔒）是 AI 的默认词汇。
• 改进： 换成普通英文；如果标签没有提供任何信息，就删掉。

结束标记

• 表现： 注释只标记代码块的结束，例如 } // end if、# End of function 或 // End processOrder。
• 原因： 右花括号已经结束了代码块。此类标记只是习惯使然，并非必要。
• 改进： 删除。在少数情况下，结束标记确实有助于理解较长的文件时，只在它能避免混淆的地方保留，不要养成这种习惯。

应有的风格

过度解释的注释

• 表现： 一条注释写了好几行，围绕一个本可用一行说明的事实，堆叠理由、背景和历史：用四行解释一个存根位于 PATH 上、哪个版本引入了这个变通方案，以及之前出了什么问题。每句话都没错，但篇幅本身就说明了问题。
• 原因： 人会留下一条注释，生成器则会写出一个案例。把一句话的事实填充成一段文字，构造“因为 X，所以 Y，进而导致 Z”的链条，或引用问题编号和修复问题的版本，这些都和其他 AI 模式一样，是多余的修饰，会把关键的一行埋在无关内容里。
• 改进： 只保留限制条件：一行，最多两行，绝不超过三行。保留平台陷阱、静默失败、协议规则和性能开销。删掉问题编号、版本历史和推理链条。

逐行解说

• 表现： 每条简单语句都有注释，逐行解说代码：// Initialize count，然后是 // Loop items，接着是 // Get item、// Increment，最后是 // Return result。
• 原因： 每一行都有注释时，没有一条注释真正重要。读者必须逐条查看，才能找到真正有意义的那一条。
• 改进： 每个逻辑块写一条简洁的注释，而不是每行都写。如果代码块不需要注释，就不要写。

生硬或夸张的措辞

• 表现： 注释听起来正式、冗长或大喊大叫，例如：“This function is responsible for validating whether the supplied credentials are valid before continuing with the authentication process”，或全大写的 // MAIN LOGIC。
• 原因： 正式而夸张的措辞读起来像生成的内容，而不像工程师留给下一位维护者的备注。
• 改进： 用自然的开发者语气写简短、采用句首大写格式的句子：// 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？
• 注释是否避免使用装饰性表情符号和结束标记？
• 注释密度是否为每个逻辑块一条，而非每行一条？
• 每条注释是否为一行；只有在第二行包含新信息时，才写两行？
• 保留下来的注释是否简短、自然，并采用句首字母大写格式？
• 是否遵守范围限制：只修改注释，不改动代码？