clean-comments

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. Match the surrounding code. Read the file and its neighbours first. The target is the comment density this codebase already uses — not zero. Stripping a well-documented module down to bare code is as wrong as leaving noise in a terse one
2. Remove obvious comments: Delete comments that merely restate what the code clearly does (e.g., // increment counter above counter++)
3. Keep complexity explanations: Preserve comments at decision points, complex algorithms, or non-obvious implementations
4. Brevity for members: Keep class and function documentation concise — one line when possible, focusing on the 'why' not the 'what'
5. Deprecation selectivity: Remove deprecated/outdated code comments unless they provide critical migration context
6. Trust readable code: If function names and parameters clearly convey purpose, additional explanation is redundant
7. When unsure, keep it. A redundant comment costs a line. A deleted comment that held the only record of why costs an afternoon

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 so the diff stays reviewable. If more files match, say which ones you left untouched — don't quietly stop at 15 and report the job done
• Focus on clarity through code structure rather than excessive documentation
• Preserve only high-value comments that answer questions the code cannot

Examples

❌ Remove (Obvious)

# 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)

# 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)

# 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.