Let comments point to missing design
Distinguish useful why comments from comments that compensate for unclear code.
The move: treat a what-comment as a design smell and a why-comment as context preservation. What belongs in a comment Use comments for external constraints, surprising trade-offs, temporary migration rules, security assumptions, and decisions that future readers cannot infer from the code alone. What should become code If the comment says what the next condition or loop does, prefer a name. isRenewalWindowOpen carries meaning better than a paragraph above a boolean expression. The review question Ask: if the implementation changes, will this comment still be true? If not, it may be duplicating the code rather than explaining the reason behind…
Sign up free — one personalized lesson every day, matched to your role and goals.
Already have an account? Sign in