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:

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:

/**
 * 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!

Comments:

[Too shy to say my name.] - Feb 20, 2006

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.

Ole Christian Rynning - Feb 21, 2006

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] - Feb 24, 2006

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

Marius Mårnes Mathiesen - Mar 15, 2006

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)); }