Symptom
Comments explaining what the next block of code does, what a function returns, or how a parameter is meant to be used.
Goal
Names of functions, variables, and types tell the reader what the comment was trying to say. Comments survive only when WHY is non-obvious.
Smellier version
// charge the customer's stored payment method, including tax
charge(c, t * 1.1);chargeWithTax(customer, total);Savings
No more stale comments; readers trust names; the code is the documentation.
Note
The code didn't reveal its intent — the comment is patching an unnamed function or unclear variable; comment and code drift over time.