coding-style

Coding Style and Best Practices

Code Commenting Best Practices

Core Principle: The best comment is the one you found a way not to write. Clear, self-documenting code is always preferable to cluttered code with extensive comments.

When to Use Comments

Good Comments:

• Legal/Copyright: Required copyright notices and authorship information
• Clarification: When translating complex logic into readable intent (but prefer refactoring)
• Warning: Alert other developers about consequences (e.g., performance implications, side effects)
• Critical gotchas: Use **Critical:** prefix for behavior that could cause bugs if misunderstood
• TODO: Mark future improvements with //TODO comments
• Intent Explanation: Document why a decision was made, not what the code does
• High-signal only: Keep comments only when they explain why or make the code much faster to understand than skimming

Examples:

// TODO: Optimize this query when we have user metrics
const posts = await db.post.findMany({ take: 1000 });

// Using 5 retries based on observed API rate limits
const MAX_RETRIES = 5;

// WARNING: This operation is expensive - cache results when possible
const analysis = await performDeepAnalysis(data);

// **Critical:** Timezone changes regenerate slots but posts keep absolute UTC time
export function regenerateSlots() { ... }

When NOT to Use Comments

Avoid These Patterns:

• Redundant Comments: Don't describe what code clearly shows
• Commented-Out Code: Delete it - version control remembers everything
• Noise Comments: Avoid obvious statements that add no value
• Journal/Attribution Comments: Use git history instead
• Closing Brace Comments: If you need these, your functions are too long
• Mandated Comments: Don't require comments on every function/variable

Bad Examples:

// ❌ BAD: Redundant comment
let count = 0; // Initialize count to zero

// ❌ BAD: Commented-out code
// const oldImplementation = () => { ... }

// ❌ BAD: Noise comment
/* getter for name */
getName() { return this.name; }