Code comments are natural-language notes placed beside code to preserve information the implementation cannot express well. Their main job is to explain why a decision exists: a business reason, a constraint, or the choice of one approach over another. Readable names, small units, and refactoring should explain implementation logic first; comments supplement them when that is not enough. section 2.2.3 section 2.5
Comments are especially useful around complex decision points. An involved conditional can be clarified with explanatory variables, smaller steps, or a concise explanation of the decision. Making that reasoning visible helps later maintenance and debugging. section 2.2.2
Comment the boundary, not the obvious
Prefer a comment that introduces the purpose of a difficult block—such as why a particular business rule is applied—over one that merely repeats what a clear statement already does. When extracting code into a helper would require an awkward signature or obscure variables shared across nearby lines, a block-level comment can retain the local flow while marking the next responsibility. section 2.2.3 section 2.5
Use comments deliberately to control future reading cost:
- Explain decisions, motivations, and tradeoffs that clean implementation code cannot reveal. section 2.2.3
- Separate substantial code blocks so readers can locate or skip a responsibility quickly. section 2.2.3
- Refactor for legibility before commenting, but do not force a refactoring that makes surrounding code harder to follow. section 2.2.3
- Review whether existing comments remain useful; both good and bad comments are worth discussing as part of documentation practice. section 2.4
A visual separation of code blocks illustrates how comments can provide navigational landmarks without splitting tightly connected code into artificial methods. section 2.2.3
Comments are not a replacement for understandable code. They can become stale or pointless, and some information may also belong in an internal wiki. A nearby comment, optionally linked to longer documentation, keeps important context close to the developer working in the IDE. section 2.2.3
