tomevault-io Comment Review Command
Purpose
Aggressively identify and remove unnecessary comments. Code must speak for itself.
Core Principle: If code needs a comment, the code is wrong. Fix the code first.
Default Stance: When in doubt, REMOVE. Comments are technical debt.
User Input
$ARGUMENTS
Interpretation Priority:
- If $ARGUMENTS provided → Follow user's request (file path,
--allfor entire project, etc.) - If empty → Check
git statusfor uncommitted changes - If no changes → Review latest commit
- Only review entire project when explicitly requested (
--allor "review entire codebase")
Comment Principles
🚫 The Comment Problem
- Comments rot: Code changes, comments don't. Result: lies in your codebase.
- Comments mask bad code: If you need a comment, your code naming or structure is wrong.
- Comments are maintenance burden: Every comment is code you must keep synchronized.
Rule of thumb: If you're writing a comment, pause and ask "How can I eliminate this with better code?"
✅ The ONLY Legitimate Comments
These are the exclusive cases where comments are allowed. Everything else MUST be removed or refactored.
| Category | Strict Criteria | Valid Examples |
|---|---|---|
| Public API Docs | External-facing APIs ONLY. Private code = no docs needed. | @param userId - The unique identifier (but NOT for internal helper functions) |
| Business Logic WHY | ONLY when domain knowledge is truly external to code | "Due to GDPR Article 17, data must be retained for 7 years" |
| External Dependencies | Third-party API constraints NOT under your control | "Stripe webhook retries 3 times with exponential backoff" (cite documentation URL) |
| Performance/Security Warnings | Counter-intuitive decisions that would surprise reviewers | "Intentionally O(n²) - n never exceeds 5 per domain requirements" |
| Complex Patterns | ONLY when pattern itself is inherently cryptic (rare) | Regex breakdown - but first try to simplify the regex itself |
| Legal/License | Copyright headers, license attribution | "MIT License", "Patent US1234567" (required by law) |
| TODO/FIXME | Must have: owner, ticket, deadline or removal condition | // TODO(@username): #1234 Remove after Q2 migration completes |
Classification Criteria
❌ REMOVE (Delete Immediately)
Default assumption: Every comment should be REMOVED unless it strictly matches a legitimate case above.
| Type | Example | Why It's Wrong | Fix |
|---|---|---|---|
| Code flow narration | // loop through users |
Code already says this | DELETE - for (const user of users) is clear |
| Obvious explanation | // increment counter above counter++ |
Insults reader's intelligence | DELETE |
| Name compensation | // get user data above getData() |
Function name is wrong | Rename to getUserData(), DELETE comment |
| WHAT instead of WHY | // validates email format |
Function name should convey this | Rename to isValidEmailFormat(), DELETE |
| Closing brace labels | } // end if |
Indentation shows structure | DELETE - proper formatting makes this obvious |
| Section dividers | // ===== Validation ===== |
Signals function is too large | Extract to separate function, DELETE divider |
| Commented-out code | // oldFunction() |
Git history exists for a reason | DELETE - use git log if you need old code |
| Outdated/lying | Comment contradicts actual code | Dangerous misinformation | DELETE IMMEDIATELY - this causes bugs |
Aggressive Rule: If a comment explains WHAT the code does (as opposed to WHY), it must be REMOVED.
⚠️ IMPROVE (Needs Refactoring)
| Type | Problem | Required Action |
|---|---|---|
| Unclear TODO | // TODO: fix later |
MANDATORY: Add owner, ticket, condition |
| WHAT explanation | // Validates user input |
Rename function to validateUserInput(), DELETE |
| Verbose explanation | Multi-paragraph comment block | Extract to documentation file, link in code comment |
| Scattered business logic | Same rule duplicated across files | Consolidate to ONE place, reference via naming |
✅ KEEP (Legitimately Required)
Strict criteria - ALL of these must be true:
- ✅ Matches ONE of the legitimate categories above
- ✅ Explains WHY, not WHAT
- ✅ Cannot be expressed through code alone
- ✅ Concise (ideally one line, max 3 lines)
- ✅ Synchronized with code (verified accurate)
- ✅ Single source of truth (not duplicated elsewhere)
Workflow
1. Determine Analysis Target
git status --porcelain
Decision Tree:
- $ARGUMENTS has specific request → Honor it
- $ARGUMENTS empty + uncommitted changes exist → Analyze changed files via
git diff - $ARGUMENTS empty + no changes → Analyze latest commit via
git show HEAD - User explicitly requests entire project (
--all) → Full project scan
2. Extract Comments
Language-specific patterns:
- TypeScript/JavaScript:
//,/* */,/** */ - Go:
//,/* */ - Python:
#,""" """ - HTML/JSX:
{/* */},<!-- -->
3. Classify with Aggressive Bias
For each comment:
1. Does it match EXACTLY one of the 7 legitimate categories?
NO → REMOVE
2. Can the information be expressed through better code?
YES → REMOVE (suggest refactoring)
3. Does it explain WHAT instead of WHY?
YES → REMOVE
4. ALL checks passed?
→ KEEP (but verify it's truly necessary)
Output Format
For Individual Files / Changes (Direct Action)
## Comment Review: {file_path}
### ❌ REMOVE Immediately ({count})
**Line {n}**: `{comment}`
**Why**: {brief reason}
**Action**: DELETED
### ⚠️ IMPROVE or Remove ({count})
**Line {n}**: `{comment}`
**Problem**: {issue}
**Options**:
1. Refactor to `{better_code}` and DELETE comment
2. If refactoring is blocked, improve to: `{better_comment}`
**Recommendation**: Option 1
### ✅ KEEP ({count})
**Line {n}**: `{comment}` - External API constraint, properly documented
Meta-Principle: Code Quality Over Politeness
Your role: Enforce high standards. Be direct, assertive, and uncompromising.
- Don't apologize for being aggressive
- Don't hedge with "might", "could", "perhaps"
- Don't ask permission to delete obvious junk
- Don't preserve comments out of politeness
Remember: Every comment you preserve is technical debt the team must maintain forever. Be ruthless.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.