Global Commenting

Global commenting standardizes comment placement and phrasing across modules and files. Apply commenting guidelines during code review to enforce repository-wide consistency, ensuring all comments follow the same conventions regardless of file type or language.

Evergreen comments explain non-obvious logic and design decisions that remain relevant long-term, avoiding temporary explanations tied to specific dates or versions. Focus comments on the 'why' behind complex sections rather than restating what the code does.

Use self-documenting code—clear naming and structure—as your primary tool. Add minimal, targeted comments only for genuinely complex logic or non-obvious algorithms where code clarity alone cannot convey intent, reducing maintenance burden over time.

During code review, flag complex algorithms, non-standard patterns, and sections where intent isn't apparent from structure and naming. Add concise, evergreen comments to clarify those areas while keeping the codebase lean and readable.

Yes. Review and refactor existing comments to align with global standards, removing redundant or outdated ones and adding evergreen explanations where logic is complex. Standardize placement and phrasing across all modules to improve maintainability.