Writing Evergreen Comments

Overview

Comments documenting change history or implementation improvements become stale and confusing. "// Refactored from legacy system" tells nothing about current purpose.

Core principle: Comments explain WHAT code does or WHY it exists, never how it's better than before.

Violating the letter of this rule is violating the spirit of documentation.

When to Use

Use for:

• File headers (ABOUTME pattern)
• Function/class documentation
• Complex logic explanation
• Non-obvious WHY reasoning

Use ESPECIALLY when:

• Refactoring code (tempted to document the change)
• Replacing implementations (tempted to explain old vs new)
• Improving code (tempted to say "better" or "enhanced")
• Reviewing old comments (tempted to preserve history)

The Rules

NEVER Document Changes or History

Comments describe present state, not past or transitions.

<Bad> ```typescript // Refactored from the old validation system // Now uses Zod instead of manual checking class Validator { validate(data: unknown) { } }

// Improved error handling - used to just throw function processRequest() { }

// Recently moved from utils/ to core/ export function helper() { }

</Bad>

<Good>
```typescript
// Validates configuration against schema
class Validator {
  validate(data: unknown) { }
}

// Returns error details to caller for proper handling
function processRequest() { }

// Shared utility for data transformation
export function helper() { }

</Good>

NEVER Add Instructional Comments

Comments document code, not instruct developers.

<Bad> ```typescript // Use this pattern instead of the old approach // Copy this when implementing similar features class NewPattern { }

// TODO: migrate all code to use this function improvedAPI() { }

</Bad>

<Good>
```typescript
// Handles async operations with automatic retry
class RetryableOperation { }

// Validates input before processing
function processInput() { }

</Good>

NEVER Explain "Better" or "Improved"

Code quality shows in behavior, not comments claiming superiority.

<Bad> ```typescript // Better than the previous implementation // More efficient validation // Enhanced error messages class Validator { } ``` </Bad> <Good> ```typescript // Validates schema in single pass, returns all errors class Validator { } ``` </Good>

ALWAYS Use ABOUTME for File Headers

Every file starts with 2-line header explaining purpose.

<Good> ```typescript // ABOUTME: Validates user input against defined schemas // ABOUTME: Provides detailed error messages for debugging

export class Validator { // ... }

</Good>

**Why ABOUTME:** Greppable pattern for finding file purposes.

```bash
grep -r "ABOUTME:" . --include="*.ts"

Quick Reference

When Refactoring

Rule: Remove old comments describing old behavior. Don't add new comments about the change.

<Bad> ```typescript // OLD: Used to validate with regex // NEW: Now uses schema validation for better accuracy function validate(input: string) { // Enhanced validation logic } ``` </Bad> <Good> ```typescript // Validates input against schema, returns structured errors function validate(input: string) { // Business logic here } ``` </Good>

Preserving Existing Comments

Critical: Never remove comments unless proven false.

// DO remove if provably wrong
// OLD COMMENT: Returns null on error
function process() {

…