Code Comments Auditor

Audit code comments and docstrings quality. Universal for any tech stack.

Purpose Verify comments explain WHY, not obvious WHAT Check comment density (15-20% ratio) Detect forbidden content (dates, author names, historical notes) Validate docstrings match function signatures Ensure comments match current code state Identify legacy comments and commented-out code Invocation Direct: User invokes for code comment quality review Pipeline: Called by ln-100-documents-pipeline (Phase 5, if auditComments=true) Workflow Scan: Find all source files (auto-detect tech stack) Extract: Parse inline comments + docstrings/JSDoc Audit: Run 6 category checks (see Audit Categories below) Score: Calculate X/10 per category Report: Output findings and recommended actions Audit Categories

Category What to Check

1 WHY not WHAT Comments explain rationale, not obvious code behavior; no restating code 2 Density (15-20%) Comment-to-code ratio within range; not over/under-commented 3 No Forbidden Content No dates/authors; no historical notes; no code examples in comments 4 Docstrings Quality Match function signatures; parameters documented; return types accurate 5 Actuality Comments match code behavior; no stale references; examples runnable 6 Legacy Cleanup No TODO without context; no commented-out code; no deprecated notes Output Format

Code Comments Audit Report - [DATE]

Compliance Score

| Category | Score | Issues |

|----------|-------|--------|

| WHY not WHAT | X/10 | N obvious comments |

| Density (15-20%) | X/10 | X% actual (target: 15-20%) |

| No Forbidden Content | X/10 | N forbidden items |

| Docstrings Quality | X/10 | N mismatches |

| Actuality | X/10 | N stale comments |

| Legacy Cleanup | X/10 | N legacy items |

| Overall | X/10 | |

Critical Findings

• [ ] [Category] path/file:line - Issue description. Action: Fix suggestion.

Recommended Actions

| Priority | Action | Location | Category |

|----------|--------|----------|----------|

| High | Remove author name | src/X:45 | Forbidden |

| Medium | Update stale docstring | lib/Y:120 | Actuality |

Scoring Rules Score Meaning 10/10 No issues 8-9/10 Minor issues (small density deviation, few obvious comments) 6-7/10 Moderate issues (stale docstrings, some forbidden content) 4-5/10 Significant issues (major density problems, outdated comments) 1-3/10 Critical issues (author names, commented-out code blocks, broken docstrings) Reference Files Comment rules and patterns: references/comments_rules.md Critical Notes Fix code, not rules: NEVER modify rules files (_rules.md, _standards.md) to make violations pass. Always fix the code instead. Code is truth: When comment contradicts code, flag comment for update WHY > WHAT: Comments explaining obvious behavior should be removed Task IDs OK: Task/Story IDs in comments help with code traceability Universal: Works with any language; detect comment syntax automatically Based on: Claude Code comment-analyzer agent patterns

Version: 3.0.0 Last Updated: 2025-12-23