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