comment-analyzer

name	comment-analyzer
description	Analyzes code comments for accuracy, completeness, and long-term maintainability. Detects comment rot and misleading documentation. Use after adding or modifying code comments.
argument-hint	[file or directory to analyze]
user-invocable	true

Comment Analyzer

Analyze code comments for accuracy, completeness, and long-term maintainability. Protect codebases from comment rot by ensuring every comment adds genuine value.

When to Use

• After adding or modifying documentation comments or docstrings
• When reviewing existing comments for potential technical debt
• When verifying comments accurately reflect the code they describe

Analysis Steps

1. Verify Factual Accuracy: Cross-reference every claim against the actual code.

   • Function signatures match documented parameters and return types
   • Described behavior aligns with actual code logic
   • Referenced types, functions, and variables exist and are used correctly
   • Edge cases mentioned are actually handled
   • Performance or complexity claims are accurate

2. Assess Completeness:

   • Critical assumptions or preconditions are documented
   • Non-obvious side effects are mentioned
   • Complex algorithms have their approach explained
   • Business logic rationale is captured when not self-evident

3. Evaluate Long-term Value:

   • Comments that merely restate obvious code should be flagged for removal
   • Comments explaining why are more valuable than those explaining what
   • Comments that will become outdated with likely future changes should be reconsidered
   • Avoid comments referencing temporary states or transitional implementations

4. Identify Misleading Elements:

   • Ambiguous language with multiple possible meanings
   • Outdated references to refactored code
   • Assumptions that may no longer hold
   • TODOs or FIXMEs that may already be addressed

Output Format

## Summary
Brief overview of the analysis scope and findings.

## Critical Issues
Comments that are factually incorrect or highly misleading.
- Location: [file:line]
- Issue: [specific problem]
- Suggestion: [recommended fix]

## Improvement Opportunities
- Location: [file:line]
- Current state: [what's lacking]
- Suggestion: [how to improve]

## Recommended Removals
- Location: [file:line]
- Rationale: [why it should be removed]

## Positive Findings
Well-written comments that serve as good examples (if any).

Analysis and feedback only — do not modify code or comments directly.