Comments in Your Code

Are comments a good thing? I know I used to believe that they were for years, starting with my days of writing Basic on an Apple IIe, through C, C++ and finally Java. But technology changes, techniques evolve and somehow, in today’s world comments in your code usually aren’t all they’re cracked up to be.

The first thing to ask about comments is does anyone ever read them in preference to looking at the code? Please let me know if you do... after all most programmers prefer to reading code. Most people, like myself, only look at comments if what’s happening in the code isn’t obvious, which really means that the code smells and could have been written better. For example, in the following code, comments have been added because the developer named an argument badly:

  /**
   * Constructor - Pass in the name of the Country.
   */
  protected WineCountry(String name) {
    super(name, nextOrdinal++);
  }

The argument is easily renamed and the useless comment removed:

  protected WineCountry(String countryName) {
    super(countryName, nextOrdinal++);
  }

If you do read the comments, you need to consider whether or not they’re misleading or inaccurate. Comments are usually both misleading and inaccurate because code evolves overtime and its associated comments never get updated and this is more prevalent in these days of iterative development, TDD and constant refactoring.

In looking at comments, you need to consider why they were added in the first place. From experience, some organisations demand that you add comments even when they’re unnecessary and clutter the code. This is usually down to some box ticking quality document that’s survived since the days of the company’s FORTRAN based mainframe and states that you must put comments in positions X, Y and Z of your source file. An example of this is having to update a file’s header comment block with details of your latest changes: something that is redundant when you use a source control system.

A new an more pervasive source of irrelevant comments are those mandated by your IDE. You know the ones I mean, you create a new class and it gets created with lots of useless comments added and even worse are those redundant, noisy comments that you add to get rid of all the yellow compiler warning markers. This is demonstrated below; these are the default Javadocs added by eclipse to generated Setter and Getter methods:

  /**
   * @return the origin
   */
  public String getOrgin() {
    return origin;
  }

  /**
   * @return the strength
   */
  public double getStrength() {
    return strength;
  }

Another hindrance is commented out code: if you need remove a method or block of code then delete it. If you need to retrieve this code at a later date either use your IDE’s undo or go to your source control system as that’s what it’s for. Never leave in blocks of commented out code.

//  public int compareTo(AbstractRetroEnum o) {
//
  //  if (o.getClass() != this.getClass()) {
  //    throw new IllegalArgumentException("Enums must be of the same type. Not: "
  //        + o.getClass() + " and " + this.getClass());
  //  }
//
  //  int retVal = ordinal - (o).ordinal;
//
  //  return retVal;
//  }

So, having had a good rant about useless comments, I have to back peddle a bit and say that there are those do provide useful information:

• Legal comments
• Comments used to clarify a point: for example defining what a regular expression string does.
• Well written, up to date Javadocs.
• Comments that warn of consequences, for example: “this test will take 3 hours to run”.
• Some TODO comments, for example: “@TODO Delete this method in the next iteration cycle as the use-case has changed. See use-case version xxxxx

So, having ranted about comments, I’m off to update my eclipse IDE so that it doesn’t add in lots of unnecessary comments and stops warning me for not stating the obvious. As Uncle Bob Martin says in his book Clean Code “Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your expression”.