Code Comments Auditor Skill

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

Agent Skills: Code Comments Auditor

Skill Files