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> <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. ```typescript // 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 | Excuse | Reality | |--------|---------| | "Developers need to know what changed" | Git history records changes. Comments describe current state. | | "This explains why refactoring was done" | Explain WHY current code exists, not what it replaced. | | "Future devs should use this pattern" | Code quality speaks for itself. Don't instruct. | | "The old comment has useful context" | If false, delete. If true, rewrite in present tense. | | "Need to mark this as 'new' temporarily" | If it's running, it's not temporary. Describe what it IS. | ## The ABOUTME Pattern **Every file starts with 2-line header:** ```typescript // 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 <Good> ```typescript // ABOUTME: Validates API requests against schemas // ABOUTME: Returns structured errors with field-level details ``` </Good> <Bad> ```typescript // This file handles validation // It was refactored from the old system ``` </Bad> ## 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) ```typescript // 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 ```typescript // 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).