Code Comments
Core principle: The best comment is the one you didn't need to write.
Hierarchy
-
Make code self-documenting (naming, structure)
-
Use type systems for contracts
-
Add comments only for WHY, never WHAT
When NOT to Comment
Avoid Why
// Get the user's name
Restates code
@param {string} email
Types already document
Stale comments Misleading > missing
When TO Comment
WHY, Not WHAT
// Use exponential backoff - service rate-limits after 3 rapid failures const backoffMs = Math.pow(2, attempts) * 1000;
Gotchas and Edge Cases
// IMPORTANT: Assumes UTC - local timezone causes date drift const dayStart = new Date(date.setHours(0, 0, 0, 0));
External Context
// Workaround for Safari flexbox bug (JIRA-1234) // Per RFC 7231 §6.5.4, return 404 for missing resources
Performance Decisions
// 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
Instead of comment Refactor to
// Get active users
const activeUsers = users.filter(u => u.isActive)
// 86400000 ms = 1 day
const ONE_DAY_MS = 24 * 60 * 60 * 1000
// Handle error case
Extract to handleAuthError(err)
TODO Format
// ✅ TODO(JIRA-567): Replace with batch API when available Q1 2025 // ❌ TODO: fix this later
Audit Checklist
-
Necessity - Can code be refactored to eliminate comment?
-
Accuracy - Does comment match current behavior?
-
Value - Does it explain WHY, not WHAT?
-
Actionability - TODOs have ticket references?