Global Commenting

Value-adding comments explain *why* code exists and clarify complex logic or non-obvious sections, not what the code does. Prioritize self-documenting code through clear naming and focused functions; add comments only for business rules, mathematical derivations, or sections that aren't immediately understandable from the code itself.

Refactor first: use clear naming, smaller functions, and logical structure to make code self-explanatory. Add comments only when the logic remains genuinely complex after refactoring—for non-obvious algorithms, domain-specific rules, or performance trade-offs that naming alone cannot convey.

Evergreen comments explain intent and design decisions that remain true as code evolves, avoiding temporary notes, change-related markers, or line-by-line explanations. Focus on the *why* so comments stay relevant through refactors and remain a reliable source of truth alongside the code.

Provide concise, high-level comments at the start of complex sections—summarize the algorithm's purpose or mathematical principle in 1–2 sentences. Let variable names, function signatures, and code structure handle the details; reserve comments for non-obvious reasoning or business context.

Self-documenting code through clear naming and structure handles most explanation, but not all. Comments remain essential for complex algorithms, non-obvious decisions, and business rules that code syntax alone cannot express. The goal is minimal, high-value comments, not zero comments.

During review, check that comments explain *why*, not *what*; avoid noise, temporary markers, and outdated information; ensure alignment with naming and structure; and verify complexity warrants explanation. Remove redundant comments and suggest refactoring if logic is too opaque after naming improvements.