Writing Evergreen Comments

Evergreen comments explain WHY code exists and the rationale behind decisions, not WHAT it does or HOW it works. Focus on intent, non-obvious design choices, and business logic rather than implementation details or change history, so comments remain valid through refactoring and maintenance.

During refactoring, document the current state and reasoning: explain why this module or function exists, what problem it solves, and any constraints or principles it follows. Avoid temporal context like "refactored from X" or "changed because Y"; instead state present-state purpose and design intent.

Comments that document change history, temporary states, or implementation mechanics quickly become misleading as code evolves. Evergreen comments prevent this by focusing exclusively on lasting intent, business rules, and non-obvious decisions that remain valid across code changes and refactors.

An ABOUTME header is a consistent, greppable two-line format placed at the top of every file to document its purpose and key details. Use it to give future maintainers instant clarity on what the file does and why it exists, supporting faster code navigation and understanding.

Explain the WHY behind complex logic—the business rule, constraint, or non-obvious decision it enforces—rather than describing the mechanics or control flow. This approach keeps comments valid as implementation details change, focusing on lasting intent instead of temporary structure.