| name | ln-170-code-comments-auditor |
| description | Audit code comments and docstrings quality across 6 categories (WHY-not-WHAT, Density, Forbidden Content, Docstrings, Actuality, Legacy). Use when code needs comment review, after major refactoring, or as part of ln-100-documents-pipeline. Outputs Compliance Score X/10 per category + Findings + Recommended Actions. |
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
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: 1.0.0
Last Updated: 2025-12-20