If You Can’t Say Anthing Useful…

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:

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:

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!

About Johannes Brodwall

Johannes is Principal Software Engineer in SopraSteria. In his spare time he likes to coach teams and developers on better coding, collaboration, planning and product understanding.
This entry was posted in Software Development. Bookmark the permalink.