Global Commenting

Evergreen comments explain the rationale and business logic behind complex decisions, not line-by-line code behavior. Focus on the 'why'—algorithmic principles, design choices, or non-obvious patterns—and let clear naming and structure convey the 'what'. This approach prevents comments from becoming outdated as code evolves.

Add comments only where logic is genuinely complex or non-obvious—clarifying algorithms, business rules, or counterintuitive decisions. Prioritize clear variable names, function structure, and meaningful code organization first. Comments should fill gaps that naming and design cannot; excessive commenting signals unclear code needing refactoring.

Document algorithms by explaining the underlying mathematical principle or business rule upfront, then reference it sparingly in the code. Use docstrings for API contracts and contextual explanations for maintainers. Keep comments concise and language-agnostic so they remain relevant across codebases and refactoring cycles.

Comments become stale when they describe temporary fixes, recent changes, or what code obviously does. Write evergreen comments tied to rationale and context, not implementation details. Review comments during refactoring to remove redundant ones and update those explaining enduring design decisions or non-obvious logic.

Yes, the principles of evergreen, self-documenting comments apply universally across any language or codebase. Focus on explaining 'why' over 'what', use meaningful naming, and keep comments minimal and relevant to future maintainers regardless of syntax or framework.

No. Well-named functions, clear logic flow, and meaningful variable names eliminate the need for descriptive comments. Add comments only to clarify complex algorithms, non-obvious decisions, or business context that naming alone cannot convey, keeping your codebase lean and maintainable.