Global Commenting

Evergreen comments explain *why* decisions were made, not *what* the code does. Focus on non-obvious logic and reasoning rather than restating syntax, so comments remain accurate as code evolves without constant maintenance.

Self-documenting code uses clear naming and structure to convey intent directly; comments then explain complex decisions and edge cases. Together they reduce cognitive load—code clarity handles the obvious, comments handle the *why*.

Remove temporal notes (dates, version markers), redundant comments that restate obvious code, and outdated explanations. Keep only comments that clarify non-obvious decisions or complex algorithms that naming alone cannot express.

Prioritize meaningful variable and function names, logical structure, and explicit code organization first. Add comments only for non-obvious *why* decisions; this reduces maintenance burden while keeping code readable across projects and languages.

Yes. Self-documenting principles—clear naming, meaningful structure, and evergreen explanations of *why*—apply to all code files and platforms. Adjust comment syntax per language but keep the same philosophy of clarity and maintainability.

During code review or refactoring, check that comments explain non-obvious decisions rather than restating code, contain no temporal references, and use naming and structure to handle simple clarity. Remove or rewrite comments that fail these criteria.