commenting-intent

# Commenting Intent ## Overview Good comments explain WHY, not WHAT. Code already shows what it does. Comments should explain intent, decisions, and non-obvious reasoning. **Core principle:** If the comment just restates the code, delete the comment or improve the code. ## Baseline Violation **Agents comment mechanics (what code does):** ❌ **Over-commenting (baseline):** ```python # Calculate subtotal by multiplying price and quantity for each item, then summing subtotal = sum(item.price * item.quantity for item in items) # Calculate tax amount based on the subtotal and tax rate tax = subtotal * tax_rate # Calculate final total by adding subtotal and tax total = subtotal + tax ``` **Problem:** Comments just restate obvious code. No value added. ✅ **Comment intent only:** ```python def calculate_total_price(items, tax_rate): """Calculate order total including tax.""" subtotal = sum(item.price * item.quantity for item in items) tax = subtotal * tax_rate return subtotal + tax # No comments needed - code is clear ``` ## What to Comment ### 1. Non-Obvious Decisions ✅ **WHY you chose this approach:** ```python def is_rate_limited(user_id, redis_client): # Using Redis instead of in-memory to support distributed rate limiting # across multiple app servers. Limit: 100 req/min per business requirements. key = f"rate_limit:{user_id}" current = redis_client.get(key) if current is None: redis_client.setex(key, 60, 1) # 60 sec TTL return False return int(current) >= 100 # Limit per product requirements doc ``` **Explains:** WHY Redis, WHY these limits, WHERE requirements came from. ### 2. Algorithms and Complex Logic ✅ **WHY this algorithm:** ```python def find_user(users, email): # Binary search requires sorted array. We sort by email on load # to enable O(log n) lookups. Worth the upfront sort cost because # lookups happen 100x more frequently than updates. return binary_search(users, email) ``` **Explains:** WHY binary search, WHY pre-sorted, trade-off reasoning. ### 3. Magic Numbers and Constants ✅ **WHY these values:** ```python MAX_RETRIES = 3 # Testing showed 3 retries handles 99.9% of transient failures TIMEOUT_MS = 5000 # API SLA guarantees < 5sec response time BATCH_SIZE = 100 # Larger batches caused memory issues in prod (incident #1234) ``` **Explains:** WHERE values came from (testing, SLA, incident). ### 4. Workarounds and Gotchas ✅ **WHY unusual code:** ```python # WORKAROUND: Library bug #456 - must call reset() twice # Fixed in v2.0 but we're on v1.8 client.reset() client.reset() ``` **Warns future maintainer:** Unusual code has reason, link to issue. ## What NOT to Comment ### Don't Comment Obvious Code ❌ **Restates the code:** ```python # Set user name to "John" user.name = "John" # Loop through items for item in items: # Process the item process(item) ``` ✅ **Let code speak:** ```python user.name = "John" for item in items: process(item) ``` ### Don't Comment Mechanics of Standard Patterns ❌ **Obvious pattern:** ```python # Initialize search boundaries to cover entire array left, right = 0, len(arr) - 1 # Continue searching while there's a valid range while left <= right: ``` ✅ **Comment intent only:** ```python def binary_search(arr, target): # Binary search for O(log n) performance on sorted array left, right = 0, len(arr) - 1 while left <= right: # ... implementation (standard pattern, no comments needed) ``` ## The Comment Test **For each comment, ask:** 1. **Does it explain WHY, not WHAT?** - WHY: "Redis for distributed limiting" ✅ - WHAT: "Get value from Redis" ❌ 2. **Would I understand without it?** - If yes: Delete comment - If no: Keep comment OR improve code clarity 3. **Does it add information beyond the code?** - Yes: Keep it - No: Delete it ## Quick Reference | Comment This | Don't Comment This | |--------------|---------------------| | WHY you chose this approach | WHAT the code does | | Non-obvious decisions | Obvious assignments | | Magic number sources | Standard patterns | | Algorithm trade-offs | Mechanics of loops/conditionals | | Workarounds and gotchas | Self-evident operations | | Business rule origins | Variable declarations | ## Real-World Impact From baseline: - Agents commented every line of simple price calculation (over-commenting) - Comments restated code without adding value - Missed opportunities to explain WHY (decisions, trade-offs) **With this skill:** Comment intent, not mechanics. ## Integration with Other Skills **For evergreen comments:** See skills/writing-evergreen-comments - no temporal context in comments **For self-documenting code:** See skills/naming-variables - good names reduce need for comments