Comments
With truly good code, comments are icing on the cake.
A comment is a block of source that the compiler will ignore.
When it comes to comments, quality is more important than quantity. Too much commenting adds noise that hides important information. Document as much as possible in the code itself. Well written code may not need comments at all. The fewer comments you write, the less chance you have of writing bad comments.
Bad comments are worse than no comments because they can misinform and mislead the reader.
Comments should not describe how the program works. That is the code. Focus on the why something is written the way it is.
Do not add comments which describe the code. It violates DRY to do so. Don't duplicate code in a comment.
Do not add comments that express something that could be enforced by the language itself.
Comments can be good to document a bit of code that is unusual, unexpected, or surprising. Do not put lies in the comments. Do not put cryptic comments in or jokes. Make the comments clear and readable. Don't type without using your brain.
Do not have comments that document how things used to be. We have version control for that. Do not knock out code by enclosing it in comments. Do not be clever and add ASCII art with comments.
Commenting should be done in a consistent way.
Comments are usually written above the code that they describe.
Be aware of comment rot-inane comments indicate you must be suspicious of the quality of the design you are looking at so unless you are refactoring everything, leave them as a warning.Â
Summary
Good programmers try to write a few good comments explaining why and helpful comments that make sense. They concentrate on writing good code rather than a bunch of comments.
Bad programmers cannot tell the difference between good and bad comments. They write comments explaining how. They don't mind if comments only make sense to themselves. They bolster bad code with many comments. They fill their source files with redundant information.
Article notes
What are icing on the cake when you have truly good code?
Comments
A [...] is a block of source that the [...] will ignore.
A comment is a block of source that the compiler will ignore.
What can be good to document unusual, unexpected, or surprising bits of code?
Comments
Should you ever use comments to express something that could be enforced by the language itself?
No
What type of programmers cannot tell the difference between good and bad comments, write comments explaining how stuff works, bolster code with many bad comments, and fill their source files with redundant code information?
Bad programmers
What type of programmers write a few good comments explaining why and helpful comments that make sense (and concentrate writing good code rather than a bunch of comments)?
Good programmers
What to do with inane comments you find?
Leave them as a warning
Where should a comment be written?
Above the code that it describes
What principle is violated when comments are written that simply describe the code (describing how, not why)?
DRY
Which is worse: bad comments or no comments?
Bad comments are WORSE
What should comments describe according to Code Craft?
Why something is written the way it is
Does well written code always need comments?
No
What does too much commenting do?
It hides important information
What is a comment?
A block of source that the compiler will ignore