If You Can’t Say Anthing Useful…

by Johannes Brodwall Posted on February 17, 2006

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.
  • Too shy to say my name.

    Obvious comments do suck when you look at the code. However, sometimes (like just before negotiating your salary or vacation plans – or for some other personal or professional reason) you might want to use the javadoc tool to generate fancy and goodlooking API documents to show someone to prove, or create the illusion of, work well done! In this case the tagline “Never, ever, say in comments what the code already says.” is not appliable as there is no code to look at, but only the generated API docs! I still agree that comments should not be verbose, but they should be there (even if they are slightly useless and redundant when you have the souce code in front of you). Keep them in dense form though.

    P.S. Wouldn't it be nice with a “do not show comments”-function in the IDE? Then we could have both clean code and nice API docs at the same time with no annoyance.

    P.S.S. Almost forgot; writing good code is just as hard as writing good comments. Some programmers are actually better at writing comments than code and in those cases having comments to read before rewriting their uncomprehensible code is nice.

  • Too shy to say my name.

    Obvious comments do suck when you look at the code. However, sometimes (like just before negotiating your salary or vacation plans – or for some other personal or professional reason) you might want to use the javadoc tool to generate fancy and goodlooking API documents to show someone to prove, or create the illusion of, work well done! In this case the tagline “Never, ever, say in comments what the code already says.” is not appliable as there is no code to look at, but only the generated API docs! I still agree that comments should not be verbose, but they should be there (even if they are slightly useless and redundant when you have the souce code in front of you). Keep them in dense form though.

    P.S. Wouldn’t it be nice with a “do not show comments”-function in the IDE? Then we could have both clean code and nice API docs at the same time with no annoyance.

    P.S.S. Almost forgot; writing good code is just as hard as writing good comments. Some programmers are actually better at writing comments than code and in those cases having comments to read before rewriting their uncomprehensible code is nice.

  • For object oriented languages I feel the class header should ALWAYS be commente.

    _Especially if the classname is a generic one like *HashTable_.

    One of many nuiances working with legacy code is figuring out in which context(s) classes are used and sometimes the mere purpose of them without reading through the entire class.

    If you call outside objects methods its useful to briefly tag them with a comment or even a @see doclet.

  • For object oriented languages I feel the class header should ALWAYS be commente.

    _Especially if the classname is a generic one like *HashTable_.

    One of many nuiances working with legacy code is figuring out in which context(s) classes are used and sometimes the mere purpose of them without reading through the entire class.

    If you call outside objects methods its useful to briefly tag them with a comment or even a @see doclet.

  • Kjetil

    Too shy: just enable automatic code folding for comments in IntelliJ. Then you can unfold if you need a close look.

  • Kjetil

    Too shy: just enable automatic code folding for comments in IntelliJ. Then you can unfold if you need a close look.

  • I just stumbled across another piece of fantastic code comments that I'd love to share. It's from the PHPUnit2 documentation, have a laugh:

    protected function setUp()
    {
    // Create the Array fixture.
    $this->fixture = Array();
    }

    public function testNewArrayIsEmpty() {
    // Assert that the size of the Array fixture is 0.
    $this->assertEquals(0, sizeof($this->fixture));
    }

    public function testArrayContainsAnElement() {
    // Add an element to the Array fixture.
    $this->fixture[] = 'Element';

    // Assert that the size of the Array fixture is 1.
    $this->assertEquals(1, sizeof($this->fixture));
    }

  • I just stumbled across another piece of fantastic code comments that I’d love to share. It’s from the PHPUnit2 documentation, have a laugh:

    protected function setUp()
    {
    // Create the Array fixture.
    $this->fixture = Array();
    }

    public function testNewArrayIsEmpty() {
    // Assert that the size of the Array fixture is 0.
    $this->assertEquals(0, sizeof($this->fixture));
    }

    public function testArrayContainsAnElement() {
    // Add an element to the Array fixture.
    $this->fixture[] = ‘Element’;

    // Assert that the size of the Array fixture is 1.
    $this->assertEquals(1, sizeof($this->fixture));
    }