ln-610-code-comments-auditor

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.

⭐25stars🔀7forks📁View on GitHub🕐Updated Jan 10, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides an automated, comprehensive audit of code comments and docstrings to ensure high-quality documentation across any tech stack. It evaluates codebases against six critical dimensions—including rationale-focused commenting (WHY-not-WHAT), comment density, and accuracy—delivering a detailed compliance score and actionable recommendations to reduce technical debt and improve maintainability.

Use Cases

  • Post-Refactoring Documentation Sync: Use after major code changes to ensure that docstrings and inline comments accurately reflect the new logic and function signatures.
  • Automated Quality Gates: Integrate into CI/CD pipelines to enforce documentation standards, preventing the introduction of 'commented-out' code or forbidden metadata like author names and dates.
  • Technical Debt Auditing: Periodically scan legacy repositories to identify stale comments, redundant 'WHAT' descriptions, and outdated TODOs that hinder code readability.
  • Developer Onboarding & Standards Alignment: Help engineering teams maintain a consistent documentation style by providing objective feedback on comment density and the quality of rationale-based explanations.
nameln-610-code-comments-auditor
descriptionAudit 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

  1. Scan: Find all source files (auto-detect tech stack)
  2. Extract: Parse inline comments + docstrings/JSDoc
  3. Audit: Run 6 category checks (see Audit Categories below)
  4. Score: Calculate X/10 per category
  5. 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: 3.0.0 Last Updated: 2025-12-23