Writing Evergreen Comments

Evergreen comments explain WHAT code does and WHY it exists, not how it changed. Focus on current behavior and purpose rather than implementation history, change logs, or comparative language. This prevents comments from becoming stale when code is refactored or modified.

Use the ABOUTME pattern: a consistent, greppable two-line file header that describes the file's current purpose and responsibility. This enables quick understanding and maintains uniformity across your codebase without relying on temporal context.

Identify comments referencing changes, history, or improvements, then rewrite them to describe present functionality instead. Remove instructional or comparative language. This ensures documentation stays relevant and accurate as code evolves.

Historical comments become misleading as code changes. Evergreen comments describe current state and rationale, ensuring they remain accurate through refactoring cycles and preventing confusion about why code exists now, not how it was built.

Yes. Evergreen comments are especially useful for documenting complex logic, function and class responsibilities, and intricate algorithms. Explain the reasoning and current behavior rather than how the logic evolved or changed over time.

Evergreen comments describe present code purpose and mechanics; change-history comments reference past modifications. Evergreen approach maintains clarity across refactoring; change-history comments decay and confuse developers unfamiliar with edit history.