Avoid Inaccurate Comments [DA2]
Tip DA2
Needless to say, if a comment is inaccurate, it’s not really providing value. If it’s inaccurate or wrong, it definitely doesn’t contribute to a greater understanding of the code and can mislead people. Avoid such comments.
Comments becoming inaccurate over time is one reason why commenting is often minimized or avoided. We’ll cover tips for keeping comments up-to-date, but inaccurate comments can create more confusion and even negative value if they lead people astray.
This issue is amplified in codebases lacking clarity through techniques like good variable names. If you can’t read the code easily but you can read the comments, you’re more likely to rely on the comments than the code. If the comments lead you astray on a wild goose chase, then they’ve wasted your time.
In well-written codebases with good variable names, disciplined commenting practices, and other elements of style that contribute to self-documenting code, “wrong” or “inaccurate” comments don’t necessarily provide zero or negative value. In such codebases when reading a wrong comment, it is often clear that one of the following is true:
The comment is wrong, but the code is correct (in which case the updating the comment was overlooked, which is easy to do).
The comment provides helpful information on the intent of the original programmer, so the code in wrong and needs to be corrected.
See the following examples for how these latter two scenarios can play out: