Skip to content

Add commented-out code & redundant-comment detector #259

Description

@cursor

Summary

Add a detector for commented-out code blocks and redundant "narration" comments — comments that restate what the next line literally does. Both are common AI-assistance artifacts and reinforce DebtLens's AI-era maintainability positioning.

Motivation

Commented-out code rots and confuses readers (version control already preserves history), and narrate-the-obvious comments add noise without intent. Neither is caught today, and both align with the product identity ("patterns that slip in when teams move fast with assistants").

Proposed behavior

  • commented-out-code: contiguous comment lines that parse as plausible code (assignments, calls, control flow, balanced brackets) above a configurable minimum line count. Conservative heuristics to avoid flagging prose, license headers, examples in docstrings, or directive comments.
  • redundant-comment (optional second rule / config-gated): single-line comments immediately above a statement that closely paraphrase the code (e.g. // increment counter above counter++). Lower confidence, advisory only.

Config: commentedOutCode.minLines, allow/ignore patterns; reuse the comment-scanning infrastructure already used by todo-comment.

Implementation surface

  • New src/detectors/commentedOutCode.ts reusing comment extraction patterns from src/detectors/todoComment.ts and src/utils/strings.ts.
  • Optionally extend to Python/Kotlin/SFC via their existing comment-aware TODO detectors.
  • Register in src/detectors/index.ts / src/config/packs.ts; docs in docs/rules.md.

Acceptance criteria

  • Flags multi-line commented-out code; ignores prose, license headers, and directive comments.
  • commentedOutCode.minLines configurable.
  • Documented with strong false-positive guidance (this rule must stay low-noise).
  • npm run test:all passes.

Difficulty: medium.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions