Writing my previous post got be thinking about code comments. I have seen a lot of bad comments in my years, and I’d like it to stop! Here are a few examples from the horror cabinet of the world of code comments.
Stating the bloody obvious
Never, ever, say in comments what the code already says. Ever:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
class Bar { /** gets the foo of the bar */ public String getFoo() {...} /** Calculates the bazzle */ public int calculateBazzle() { // initialize return value to zero int returnValue = 0; // increment return value by one returnValue++; ... } |
This just makes me want to scream. If you can’t say anything useful, say nothing at all!
Oh yeah: The same goes for XML file comments.
IDE generated comments
I wonder how much code is in production with stuff like the following:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
/** * Class Bar was generated by IDEA on Feb 17th 2006 by * jbr. * @author jbr */ public class Foo { /** * Method bazzle comment. * @param arg1 * @param arg2 * @return */ public Object bar(String arg1, String arg2) { ... } } |
If the author of the comment couldn’t even read it for long enough to see that it was not appropriate – who else will benefit from it? And what good does empty @param and @return Javadoc comments do?!?
The totally dense comment
Writing good comments is really hard. Writing is hard, period. Many comments are too verbose and too hard to understand to actually be of any use, An easy track to fall into when you notice that a comment is hard to understand, is to add more text! This is like trying to extinguish a fire with gasoline.
I wish I could find an example like this, but I’d rather not insult anyone. If you have a comment, that you have written, that is verbose and/or dense: Sense it to me, and I will publish it for public humiliation.
You may laugh at this, but unless you never write comments, you have committed this cardinal sin yourself. Several times. Writing good comments is hard
Conclusion (?)
Good comments makes code much more pleasant to work with. But bad comments are just a waste. I feel like I see almost as much bad comments as good comments these days.
Leave a file as if though you would never have a second chance to fix it. Chances are that you never will come back to it. If you can’t be bothered to fix the IDE-generated comment: Turn it off and delete it. If you can’t be bothered to write something meaningful: Don’t write anything at all.
It seems like a substantial fraction of otherwise sane Java-programmers think that a poor or nonsensical comment is better than no comment at all. This madness has to stop!
