---

name: documenting-code-comments description: Standards for self-documenting code and minimal comments. Use when auditing inline documentation or deciding when comments add value vs clutter.

Code Comments

Core principle: The best comment is the one you didn't need to write.

Hierarchy

1. Make code self-documenting (naming, structure)
2. Use type systems for contracts
3. Add comments only for WHY, never WHAT

When NOT to Comment

When TO Comment

WHY, Not WHAT

Copy// Use exponential backoff - service rate-limits after 3 rapid failures
const backoffMs = Math.pow(2, attempts) * 1000;

Gotchas and Edge Cases

Copy// IMPORTANT: Assumes UTC - local timezone causes date drift
const dayStart = new Date(date.setHours(0, 0, 0, 0));

External Context

Copy// Workaround for Safari flexbox bug (JIRA-1234)
// Per RFC 7231 §6.5.4, return 404 for missing resources

Performance Decisions

Copy// Map for O(1) lookup - benchmarked 3x faster than array.find() at n>100
const userMap = new Map(users.map(u => [u.id, u]));

Refactor Before Commenting

TODO Format

Copy// ✅ TODO(JIRA-567): Replace with batch API when available Q1 2025
// ❌ TODO: fix this later

Audit Checklist

1. Necessity - Can code be refactored to eliminate comment?
2. Accuracy - Does comment match current behavior?
3. Value - Does it explain WHY, not WHAT?
4. Actionability - TODOs have ticket references?