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

# 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