Write comments that survive aislop - Scanaislop Documentation

aislop does not ban comments. It bans comments that make code noisier without adding information. Keep comments that explain a non-obvious constraint, an external workaround, a data contract, or an invariant the type system cannot express. Delete comments that repeat nearby code.

Decision tree

Run every comment through this checklist before keeping it.

Check the name first

If the function, variable, or file name already says what the comment says, delete the comment. Rename the symbol if the name is weak.

Delete what-comments

Comments that describe what the next line does are usually redundant. The code is already the source of truth for what happens.

Keep why-comments

Keep short notes that explain a non-obvious reason: a third-party bug, a protocol constraint, a compatibility workaround, or an invariant reviewers cannot infer locally.

Bad and good examples

Trivial restatement

Bad:

// Initialize the user service
const userService = new UserService();

Good:

const userService = new UserService();

The name already says what the comment says.

Narrative JSDoc

Bad:

/**
 * Heuristic side-effect detection. Walks an expression subtree
 * and flags anything that could invoke code when the declaration
 * initializes.
 */
export const hasSideEffect = (node: Node): boolean => {
  // ...
};

Good:

/**
 * @deprecated Use {@link hasObservableEffect}. This predicate
 * under-counts dynamic property access.
 */
export const hasSideEffect = (node: Node): boolean => {
  // ...
};

The first block restates the function. The second carries a contract that editors and callers can use.

Decorative separators

Bad:

// --- Classification -------------------------------------------------
// Per-engine planning, building rows from a discovered project
// -------------------------------------------------------------------
export const classify = () => {
  // ...
};

Good:

export const classify = () => {
  // ...
};

If a file needs section banners to stay readable, split it into smaller files.

Phase headers

Bad:

// Phase 1: Code changes
await runLint();
await runDeps();

// Phase 2: Formatting
await runFormat();

Good:

await runLint();
await runDeps();

await runFormat();

Whitespace already groups the steps.

JSDoc that earns its place

Keep JSDoc when it has machine-readable value or explains a public contract.

Keep	Why
`@deprecated`	Editors and type tooling can warn callers
`@see` / `@link`	Typed references survive renames better than prose
`@example`	Useful for public APIs and library exports
`@param` / `@returns`	Useful only when the semantic meaning is not obvious from the name and type

Delete JSDoc that summarizes an internal helper, repeats parameter names, or narrates implementation steps.

Rules involved

Rule	What it flags	Fixable
`ai-slop/trivial-comment`	Adjacent comments that restate code	Yes
`ai-slop/narrative-comment`	Decorative banners, phase headers, JSDoc preambles without meaningful tags, and AI-narration prose	Yes
`ai-slop/meta-comment`	Comments about implementation phases, generated-code process, or agent behavior	Usually

Run:

aislop fix

The fixer removes comments that are mechanically safe to delete and verifies the file still parses before writing the result.

​Decision tree

​Bad and good examples

​Trivial restatement

​Narrative JSDoc

​Decorative separators

​Phase headers

​JSDoc that earns its place

​Rules involved

Decision tree

Bad and good examples

Trivial restatement

Narrative JSDoc

Decorative separators

Phase headers

JSDoc that earns its place

Rules involved