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.

// 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() { }

NEVER Add Instructional Comments

Comments document code, not instruct developers.

// 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() { }

NEVER Explain "Better" or "Improved"

Code quality shows in behavior, not comments claiming superiority.

ALWAYS Use ABOUTME for File Headers

Every file starts with 2-line header explaining purpose.

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.

Preserving Existing Comments

Critical: Never remove comments unless proven false.

// DO remove if provably wrong
// OLD COMMENT: Returns null on error
function process() {
  throw new Error(); // ← Comment was false, remove it
}

// PRESERVE if still accurate
// Retries up to 3 times before failing
function fetch() {
  // Even if you refactor, keep comment if behavior same
}

Red Flags - STOP and Rewrite

If you catch yourself writing:

• "Refactored", "Improved", "Better", "Enhanced", "New"
• "Old", "Legacy", "Previously", "Used to"
• "Recently", "Now", "Updated", "Modern"
• "Use this instead", "Copy this pattern", "Migrate to"
• "Was", "Changed from", "Moved from", "Unified"

STOP. Write comment describing current behavior and purpose.

Common Rationalizations

The ABOUTME Pattern

Every file starts with 2-line header:

// ABOUTME: First line - what this file does
// ABOUTME: Second line - key details or context

// Rest of file...

Guidelines:

• Exactly 2 lines
• Each starts with ABOUTME:
• Greppable and scannable
• Describes file purpose

Verification

Before committing comments:

• Explains WHAT or WHY (not "what changed")
• No temporal context
• No references to old implementations
• No instructional language
• File has ABOUTME header (2 lines)
• Existing accurate comments preserved
• No "new", "old", "improved", "refactored"

Real-World Examples

Bad Comments (Don't Do This)

// ABOUTME: New validation system
// ABOUTME: Refactored from old regex approach

// This replaces the old validator - use this instead
// Better error handling than before
class Validator {
  // Enhanced validation logic (improved from v1)
  validate(data: unknown) { }
}

Good Comments

// ABOUTME: Validates configuration against schemas
// ABOUTME: Returns all errors in single pass

// Validates data structure and types
// Returns structured errors with field paths
class Validator {
  // Checks each field against schema rules
  validate(data: unknown) { }
}

Integration with Naming

See skills/naming-by-domain for domain-focused naming (no temporal context in names either).