quality-code-comments

title: Code Comment Guidelines
impact: MEDIUM
impactDescription: Excessive comments add noise; missing comments hurt maintainability
tags: comments, documentation, readability

Code Comment Guidelines

General Principle

Keep comments limited and avoid obvious ones. Comments should explain "why" not "what" - the code itself should be clear enough to explain what it does.

When to Comment

• Business decisions or domain logic that isn't obvious from the code
• Workarounds or hacks with explanation of why they're needed
• Non-obvious performance optimizations
• Important security considerations
• Troubleshooting context (e.g., why a particular approach was chosen after hitting issues)

If none of these apply, skip the comment entirely. The function name, parameters, and return type should speak for themselves.

When NOT to Comment

// ❌ Bad - Obvious comment
// Get the user
const user = await getUser(userId);

// ❌ Bad - Restating the code
// Loop through bookings
for (const booking of bookings) {
  // Process booking
  processBooking(booking);
}

Good Examples

// ✅ Good - Explains why, not what
// We need to fetch availability before slots because the timezone
// conversion depends on the user's configured availability rules
const availability = await getAvailability(userId);
const slots = convertToSlots(availability, timezone);

// ✅ Good - Documents a non-obvious constraint
// Google Calendar API has a 2500 event limit per sync request
const BATCH_SIZE = 2500;