# Clean Comments

> Remove unnecessary, redundant, or obvious code comments while preserving valuable explanations. Use when cleaning up comments, removing verbose documentation, simplifying inline comments, or preparing code for review.

- Skill: `majiayu000/clean-comments` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/clean-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/clean-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/clean-comments

---


# Comment Cleanup

This guide is for removing unnecessary, redundant, or obvious code comments while preserving valuable explanations. Use this when cleaning up verbose documentation or preparing code for review.

## Core Principles

1. **Remove obvious comments**: Delete comments that merely restate what the code clearly does (e.g., '// increment counter' above 'counter++')
2. **Keep complexity explanations**: Preserve comments at decision points, complex algorithms, or non-obvious implementations
3. **Brevity for members**: Keep class and function documentation concise - one line when possible, focusing on the 'why' not the 'what'
4. **Deprecation selectivity**: Remove deprecated/outdated code comments unless they provide critical migration context
5. **Trust readable code**: If function names and parameters clearly convey purpose, additional explanation is redundant

## Review Criteria

When reviewing code, ask yourself:
- Does this comment add value beyond what well-named code already communicates?
- Does it explain business logic, edge cases, or architectural decisions? → **Keep**
- Could this comment block be reduced to a single meaningful line? → **Simplify**
- Is this a TODO/FIXME comment referencing completed work? → **Remove**
- Would this help a new developer understand non-obvious behavior? → **Keep**

## Batch Processing

- Process **max 15 files per session** for manageable reviews
- Focus on clarity through code structure rather than excessive documentation
- Preserve only high-value comments that answer questions the code cannot

## Examples

### ❌ Remove (Obvious)
```python
# Increment the counter
counter += 1

# Check if user is None
if user is None:
    return

# Loop through items
for item in items:
    process(item)
```

### ✅ Keep (Valuable)
```python
# Use exponential backoff to avoid overwhelming the API
# Max retries: 3, delays: 1s, 2s, 4s
retry_with_backoff(api_call)

# IMPORTANT: Must validate before save to prevent orphaned records
# See issue #1234 for context
if not validator.check(data):
    raise ValidationError

# Performance: O(n log n) - don't change to bubble sort
quicksort(data)
```

### 🔄 Simplify (Verbose → Concise)
```python
# Before:
# This function calculates the total price by iterating through
# all items in the cart, multiplying each item's quantity by its
# price, and then summing all the results together to get the final total.
def calculate_total(cart):
    return sum(item.quantity * item.price for item in cart)

# After:
# Includes bulk discount calculation for quantities >10
def calculate_total(cart):
    return sum(item.quantity * item.price for item in cart)
```

## Output

The output should be the cleaned code with only high-value comments remaining. Each preserved comment should answer questions that the code itself cannot.

**Remember**: The best comment is often no comment when the code speaks for itself.