ai-slop/narrative-comment auto-fixable

Narrative comment.

A multi-line comment block that walks through what the function does in prose. The signature already says it; the prose is decorative.

Bad — what an agent ships

// This function takes a user ID and a list of orders,
// filters the orders to only those belonging to the user,
// then sums the total amount across them and returns it.
function sumUserOrders(userId: string, orders: Order[]): number {
  return orders
    .filter(o => o.userId === userId)
    .reduce((sum, o) => sum + o.amount, 0)
}

Good — what aislop hands back

function sumUserOrders(userId: string, orders: Order[]): number {
  return orders
    .filter(o => o.userId === userId)
    .reduce((sum, o) => sum + o.amount, 0)
}

Why an AI agent produces this

Agents are trained to "explain" code. They pad function bodies with explanatory preambles even when the signature, parameter names, and operator chain already tell the same story.

Provenance

How this rule is justified.

Rule id

ai-slop/narrative-comment

Enforcing engine

ai-slop

Detector strategy

Deterministic comment-block parse: flags consecutive comment lines that paraphrase the immediately following declaration.

Legitimate code that is NOT flagged

WHY comments, license headers, doc comments documenting public API contracts, and comments stating a non-obvious constraint are not flagged.

Evidence

Verbosity signals derive from SlopCodeBench, which measured comment padding in long-horizon coding tasks, and recurred across the first public scan batch.

← All patterns Scan your repo for this →