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