SlopScore for Code

Patterns / Over-commented boilerplate

Over-commented boilerplate

Models comment the way tutorials do, one line of English per line of code. It makes generated code look careful. For a reader it doubles the length and hides the few comments that matter.

What it looks like

// Import the required modules
// Initialize the total variable
// Loop through the items
// Return the result
// ===== Helper Functions =====
// Step 1: Validate input

Why it matters

Comments that restate code go stale silently: the code changes, the comment doesn't, and now it's wrong.

Before and after

Before
// Initialize the total
let total = 0;
// Loop through the items
for (const item of items) {
  // Add the price to the total
  total += item.price * item.qty;
}
// Return the total
return total;
After
// qty can be fractional for weight-priced items, so don't round here
let total = 0;
for (const item of items) total += item.price * item.qty;
return total;

How to fix it

  1. Delete comments that say what the next line does.
  2. Keep comments that explain why: a business rule, a workaround, a gotcha.
  3. Replace section banners with smaller files or well-named functions.

When it's fine

Doc comments on public APIs (JSDoc, docstrings) and comments that explain non-obvious intent.

Catch this automatically. SlopScore for Code checks every pull request for this pattern (rule over-commented) and 11 others. Score a public PR or add the free GitHub Action.

Related