Comments are only really acceptable for legal purposes or complex code that can't be changed to be easier to read.
Don't comment bad code to explain it, fix it.
Comments tend to pollute and congest code bases and even often mislead the reader rather than help the readability of code.
Hard to maintain as code evolves, as what you're describing what necessarily stay the same.
Comments Do Not Make Up for Bad Code
Rather than spend time commenting the code that is a mess, spend that time cleaning the mess.
Explain Yourself in Code
Explained in previous chapters, we should be using good code readability practices to ensure that code reads well and explains itself.
I believe that SRP principle helps achieve this significantly as demonstrated in the example.
Good Comments
Legal comments like authorship or copyright statements are necessary in code bases sometimes.
Informative comments like explaining what an abstract method returns, however it is preferable to have the function name describe this.
Explanation of intent comments like an author taking an interesting approach to a problem, you may not agree with the approach but at least you know what he is trying to do.
Clarification comments like translating the meaning of an obscure argument or return value. Although we should try to make this clear through code, we don't have much of a say if what we are using is not our code, so clarifying comments may be useful here.
Must ensure that our clarifying comments are in fact correct!
Warnings, it can be useful to warn users of potential risks of using a function or something of the sort.
TODO comments can be useful for notifying readers that a function is "in the works" or of a degenerative implementation that needs to be updated.
Amplification comments can be good to notify a reader that some code that may not seem important actually plays a large role.
Javadocs are very useful when writing a public API.
Bad comments
Mumbling comments are when you put in a comment just because you feel like you should, no real thought has gone into it.
Redundant comments are when the comment doesn't provide any value, useless reading... the code already describes itself.
Misleading comments are inaccurate comments or comments with misinformation or lack of information that can lead to incorrect or bad assumptions about the code.
Mandated comments are comments that are their for the sake of having a comment, like saying "every function needs a comment", this will just clutter the code base.
Journal comments are to keep track of edits but with version control systems now, these are redundant and not necessary. They're just clutter.
Noise comments are ones that restate the obvious and provide no valuable information.
Don't Use a Comment When You Can Use a Function or a Variable
Position Markers
Grouping code together with big comments lines like:
// Actions ///////////////////////////////////
This is clutter and should be avoided, very rarely is this necessary.
Closing Brace Comments
Refers to comments at the end of braces to show what that brace belongs to, these are redundant noise.
We should be trying to shorten our functions instead.
Attributions and Bylines
Once again version control is very good at keeping track of who does what.
Making this attribution comments also redundant.
Commented-Out Code
Once again version control systems make it possible to retrieve old code.
Therefore we mustn't be afraid of losing old code if we end up needing it again.
If code is commented out and not being used it should be eliminated.
HTML Comments
"HTML in source code comments is an ABOMINATION"
If comments are to be extracted by some tool, it should be the responsibility of that tool and not the programmer.
Non-local Information
Comments shouldn't give too much information.
If there is even a comment it should only provide local information not system or global information.
Too Much Info
Don't put historical discussions or irrelevant descriptions in code, it only clutters it.
Inobvious Connection
If you are going to write a comment you want it to be obvious what code the comment refers to.
Function Headers
Short functions don't need headers, it should describe itself.
If we construct our functions properly with care, most if not all of our functions should be relatively short.
Javadocs in Non-public Code
If code is not intended for public consumption, generating documentation pages is not really useful.
The extra formality of the javadoc comments amounts to cruft and distraction.