Discussion on: Bullsh*t Of Self-Documenting Code

There are bad comments, and good comments.

There is bad code, and good code. And bad code can be written in any programming language.

What I consider a bad comment is:

• one that repeats what the code is doing. i += 1; // add 1 to i.
• explains what, rather than changing the code to make the comment unnecessary. int i; // height instead of int height;
• explain unclear code, rather than changing the code to be clear (when/where possible)
• comments that are incorrect, because they are old/stale and the code has changed
• commented out code
• metadata comments, which should be managed by the version control system (usually seen in old code before everyone used version control systems)

What I consider good comments is:

• expository block comments that explain when/why to use something
• architectural block comments, for how things fit together
• comments that list preconditions
• comments that explain why some oddball code exists, such as to fix a particular bug (a great breadcrumb to be able to verify if the oddball code is still necessary)
• explain non-idiomatic code, as a caution to the next developer who may mistakenly think something can be simplified into idiomatic code
• marking incomplete implementations