Commenting Intent

Comments explaining WHY capture the intent, trade-offs, and constraints behind code that self-documenting syntax cannot convey. A comment like 'MAX_RETRIES = 3 # Based on testing showing 3 retries handles 99.9% of transient failures' guides future maintainers on decision rationale, preventing unnecessary changes and speeding code reviews.

Redundant comments merely restate obvious code mechanics. Remove comments like '# Add a and b to get total' above total = a + b. Keep only comments explaining non-obvious logic, workarounds, magic numbers, algorithm choices, or constraints—information the code itself cannot express.

Document the WHY behind algorithm selection, non-obvious decision points, and trade-offs accepted. Include justifications for magic numbers, explanations of workarounds necessitated by bugs or external constraints, and references to decision origins—information that helps maintainers understand intent without reverse-engineering reasoning.

Strike balance by commenting only where code intent is unclear: complex branching logic, performance optimizations, unusual workarounds, and justified defaults. Self-evident operations like variable assignments and simple loops need no comments; focus effort on explaining non-obvious decisions and trade-offs.

Yes. Comments explaining rationale and decision origins accelerate code review by eliminating back-and-forth questions about intent. New maintainers onboard faster when comments document gotchas, constraints, and design choices upfront rather than forcing them to deduce reasoning from code structure.