No commented-out code blocks

Commented-out code blocks leave the reader uncertain about whether the code represents a previous implementation, a planned alternative, or a debugging remnant. That uncertainty slows every code review. ISO 25010 maintainability.analysability degrades: developers must read and evaluate code that does nothing. Files with large blocks of commented code are harder to grep and diff, and they create review fatigue that causes reviewers to miss real issues. If the code is needed, it belongs in a branch. If it is not needed, git history already preserves it.

Delete commented-out code blocks and rely on git history for recovery:

# Find large comment blocks (heuristic)
grep -r "^[[:space:]]*//' src/ | grep -v "eslint\|@\|TODO\|FIXME\|http" | head -50

Commit each removal with a message describing what was deleted: remove commented-out legacy auth implementation. If recovery is needed later, git log -S 'deletedFunctionName' finds the commit. Use feature branches for in-progress alternatives instead of comment blocks.

• ID: code-maintainability.code-hygiene.no-commented-code

• Severity: low

• What to look for: Search source files for blocks of commented-out code — these are typically multi-line // or /* */ comments that contain syntactically valid code (function calls, assignments, JSX, etc.) rather than explanatory prose. Single-line commented examples in documentation comments don't count. Look for:

  • Functions or component definitions wrapped in comments
  • Commented-out import statements
  • Alternative implementations left in comments
  • Old code left "just in case"

• Pass criteria: Count all commented-out code blocks across the codebase (multi-line blocks of syntactically valid code in comments). No more than 2 isolated single-line instances across all files. Report the count: "Found X commented-out code blocks across Y files."

• Fail criteria: 3 or more commented-out code blocks found across the codebase, or any file that has more than 5 consecutive lines of commented-out code.

• Skip (N/A) when: The project has fewer than 5 source files. Signal: fewer than 5 source files.

• Detail on fail: "Commented-out code found in 4 files: components/UserCard.tsx (12 lines of old implementation), lib/api.ts (old fetch logic in comments), app/api/users/route.ts (2 alternative handler implementations in comments)." or "app/page.tsx contains 30 lines of commented-out JSX from an earlier design iteration."

• Remediation: Commented-out code clutters files and creates cognitive overhead. If the code is needed, it should be in a branch. If it's not needed, it should be deleted — git history preserves it if you ever need it back.

  # Find files with large comment blocks (heuristic)
  grep -r "^[[:space:]]*//" src/ | grep -v "eslint\|@\|TODO\|FIXME\|http" | head -50
  

  Delete the commented code, commit with a clear message (remove commented-out legacy auth implementation), and rely on git history for recovery if needed. git log -S 'deletedFunctionName' will find the commit that removed it.