etylsarin/code-commenting

Code Commenting

Comment WHY, not WHAT. Prefer renaming over commenting.

When to Comment

| Situation | Action | |-----------|--------| | Self-explanatory code | No comment | | Bad name is the real problem | Rename instead | | Complex business logic / non-obvious algorithm | Comment WHY | | Regex, API constraints, gotchas | Comment WHY | | Public API function/method | JSDoc | | Magic number / config constant | Inline rationale |

Examples

// ✗ Obvious
let counter = 0; // Initialize counter to zero

// ✓ WHY
// Apply progressive tax brackets: 10% up to 10k, 20% above
const tax = calculateProgressiveTax(income, [0.1, 0.2], [10000]);

// ✓ Algorithm rationale
// Floyd-Warshall: need all-pairs distances, not just single-source
for (let k = 0; k < vertices; k++) { /* ... */ }

// ✓ API constraint
// GitHub API: 5000 req/hr for authenticated users
await rateLimiter.wait();

// ✓ Config rationale
const MAX_RETRIES = 3;     // network reliability baseline
const API_TIMEOUT = 5000;  // Lambda max is 15 s — leave headroom

Public APIs — JSDoc

/**
 * @param principal - Initial amount
 * @param rate - Annual rate as decimal (0.05 = 5%)
 * @param time - Years
 * @param n - Compounds per year (default 1)
 * @returns Final amount
 */
function calculateCompoundInterest(principal, rate, time, n = 1) { ... }

Annotation Tags

| Tag | Use | |-----|-----| | TODO | Planned work | | FIXME | Known bug needing fix | | HACK | Workaround — note why and when to remove | | NOTE | Important non-obvious constraint | | WARNING | Side effect / mutation risk | | PERF | Hot path — optimization opportunity | | SECURITY | Security-sensitive code | | DEPRECATED | Note replacement and removal version |

Anti-Patterns

| Anti-pattern | Rule | |--------------|------| | Commented-out code | Delete it — git has history | | Changelog in comments | Use git log | | Decorative dividers | Use proper file/section structure |

Checklist

• [ ] Explains WHY, not WHAT
• [ ] Still accurate after the change
• [ ] Adds genuine value
• [ ] Placed above the code it describes