Writing Evergreen Comments

# 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

| Bad Comment | Why Bad | Good Comment |
|-------------|---------|--------------|
| `// Refactored from legacy` | Temporal context | `// Handles user authentication` |
| `// New error handling` | References change | `// Returns errors to caller` |
| `// Improved performance` | Claims improvement | `// Caches results for 5min` |
| `// Use this instead of X` | Instructional | `// Validates async` |
| `// Wrapper around API` | Implementation | `// Fetches user data` |
| `// Recently moved here` | Temporal context | `// Shared validation logic` |

## 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>

<Goo