/antislop-code

name: antislop-code
description: "Code comment hygiene for AI coding agents: remove generic AI-slop comments, keep the valuable ones, never touch the code."
allowed-tools: Read Write Edit Glob Grep

antislop-code

> Anti Slop: Rules for AI Coding Agents. Code Comments skill

> Part of the antislop system. Read together with `antislop.md` (the core). This skill filters comments that read as generically AI (decorative, restating the obvious, stiff, loud) while preserving the comments that carry real information. It references core rules by number and never duplicates or renumbers them. Load it when the task writes or edits code comments.

How to use this skill

• Load together with `antislop.md` whenever the task touches code comments. The core holds the mechanism (the purpose test, the three tiers, the Delivery Gate); this skill holds comment-specific depth.
• Every entry has the same shape: **Tell** (the pattern), **Why** (why it reads as slop), **Fix** (what to do instead), with the governing core rule cited as R-XX.
• **Scope guardrail:** this skill only modifies comments. Never modify executable code, identifiers, imports, formatting, indentation, whitespace, control flow, or logic. When in doubt, leave the code untouched.
• The Delivery Gate in the core remains the gate. The "Code Comment Checklist" at the end of this file is the comment-specific supplement to run alongside it.

Comments That Add Nothing

Decorative Separators

• **Tell:** banner comments built from repeated characters, ALL CAPS labels, or box drawing around a section name: `// =======================` around `Authentication`, `// -------- WORKFLOW --------`, or a `/* ---- ROUTES ---- */` header.
• **Why:** the decoration is the message. A label wrapped in `=` or `-` signals "AI made this" without adding information, and ALL CAPS reads as shouting.
• **Fix:** replace with a single plain line, or remove entirely if the label adds nothing (R-31).

Restating the Obvious

• **Tell:** a comment that repeats what the next line or declaration already shows, like `// Initialize the variable` above `let count = 0`, `// User class` above `class User {}`, `// Validate user` above `function validateUser()`, or `const userAge = 25; // User age is 25`.
• **Why:** it doubles the reading load without adding anything. The code already says it; the comment just repeats it.
• **Fix:** remove and leave the line of code alone.

Workflow Narration

• **Tell:** comments that narrate the flow step by step, like `// Step 1: Validate input`, `// Step 2: Process request`, `// Step 3: Return response`, or `// First...`, `// Next...`, `// Finally...`.
• **Why:** the control flow is visible in the code itself. Numbering it reads as a checklist, not an explanation.
• **Fix:** remove. If the flow is genuinely hard to follow, that is a structure problem, not a missing comment problem.

Empty Labels

• **Tell:** generic labels with no information behind them: `// Main logic`, `// Core logic`, `// Business logic`, `// Helper function`, `// Entry point`, `// Error handling`, or `// Note: This is important.` / `// Important: Please read.`
• **Why:** the label names a category, not a fact. "Main logic" tells the reader nothing they could not infer from the code.
• **Fix:** remove unless the label carries specific information. "Note: retries happen only on 5xx" earns its place; "Note: this is important" does not.

Vague Placeholders

• **Tell:** comments that promise future work without saying what: `// TODO: Improve this`, `// Future improvements`, `// Additional optimization can be added here`, `// Add more validation`.
• **Why:** a vague TODO is noise. It names a feeling (this could be better) instead of a task (what, and why).
• **Fix:** remove. Keep a TODO only when it names a specific task with enough context to act on.

Signature Echo

• **Tell:** documentation that only restates the signature, like a JSDoc block that repeats `@param price The price.` and `@returns Total price.` for a function whose name and parameters already say all of it.
• **Why:** docs that echo the signature add length, not understanding. The reader learns nothing new.
• **Fix:** simplify or remove the echo. Keep documentation that explains business rules, edge cases, assumptions, algorithms, limitations, side effects, API behavior, or security implications. Never strip real documentation.

Decorative Emoji

• **Tell:** emoji used as decoration in comments, like `// ✅ Validation` or `// 🚀 Performance`.
• **Why:** emoji is visual noise in code, and the specific set (✅, 🚀, 🔒) is the AI default vocabulary.
• **Fix:** replace with plain English, or remove if the label adds nothing.

End Markers

• **Tell:** comments that only mark the end of a block, like `} // end if`, `# End of function`, or `// End processOrder`.
• **Why:** the closing brace already ends the block. The marker exists out of habit, not need.
• **Fix:** remove. In the rare case an end marker genuinely helps a long file, keep it only where it prevents confusion, not as a habit.

How It Should Read

The Over-Explained Comment

• **Tell:** one comment that runs on for several lines, stacking reasons, context, and history around a fact that fits in one line: a four-line block explaining that a stub sits on PATH, which release introduced the workaround, and what broke before it. Every sentence is true. The length is the tell.
• **Why:** a person leaves a note, a generator writes a case. Padding a one-line fact into a paragraph, building a "because X, so Y, and therefore Z" chain, or citing the issue number and the version that fixed it are the same flourish as any other AI pattern, and they bury the one line that matters under the ones that do not.
• **Fix:** cut to the constraint alone: one line, two at most, never three. Keep the platform trap, the silent failure, the protocol rule, the performance cost. Drop the issue number, the version history, and the reas