no-ai-obvious-comments

Type: problem · Default: warn · Fixable: No

A comprehensive, multi-faceted comment linter that strictly enforces professional comment standards regarding density, vertical/horizontal limits, and content quality.

Why This Rule Matters

Instead of outright banning comments, this rule enforces a high bar for comment quality. AI assistants are prone to generating excessive, overly verbose, or obvious comments that restate what the code already says. This rule ensures comments are concise, necessary, and explain why rather than what.

How Detection Works

This rule evaluates every comment in the file against four distinct criteria:

1. Density Control (Comment-to-Code Ratio)

To prevent files from becoming overwhelmed with comments, the rule enforces a strict density limit:

• Maximum 20% comment lines for files with >= 50 lines.
• Maximum 30% comment lines for smaller files (< 50 lines).

2. Horizontal Limit

Every comment line must be 80 characters or fewer (including indentation and markers like //). This prevents massive, horizontally scrolling walls of text often generated by AI.

3. Vertical Limit (Consecutive Lines)

Comments are grouped into consecutive blocks. The limit depends on their location:

• Docstrings (comments immediately preceding a function declaration/expression): Maximum 10 lines.
• Inline Logic (all other comments): Maximum 3 lines. If a comment block exceeds these limits, it should be moved to external documentation or linked.

4. Content Quality

• Commented-Out Code: Detects leftover code (using heuristics like const, function, =>) and throws an error urging the use of Version Control instead.
• Obvious Comments: Checks for overlap between the comment's words and the tokens of the immediately following statement. Throws an error if the comment simply repeats the code's function (e.g. // increment i over i++).

Examples

❌ Invalid

// 1. Density Limit Violation
// A file with 5 lines of code and 10 lines of comments 
// will fail the 30% density threshold.
const x = 1;

// 2. Horizontal Limit Violation
// This comment line is completely excessive and exceeds the 80 character limit that we have strictly set to ensure vertical readability.

// 3. Vertical Limit Violation (Inline)
// We need to loop over the array
// and then we will filter out the bad values
// because the API sometimes returns null
// and we don't want our app to crash.
const validData = data.filter(Boolean);

// 4. Commented-out code
// const oldData = fetchOldAPI();
const data = fetchNewAPI();

// 5. Obvious comment
// increment counter
counter += 1;

✅ Valid

// Process user data carefully due to DST edge cases
function processUser(user) {
  // We filter nulls because the legacy API can return sparse arrays
  const validData = user.data.filter(Boolean);
  
  return validData;
}

Options

This rule currently has no configuration options. The thresholds (20%/30% density, 80 chars width, 10/3 lines vertical) are strictly enforced to guarantee a professional baseline.