Antislop Code

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