/** no comment */

Chris Justus managed to totally miss my point. He assumes that I was advocating for crappy uncommented code. That is not the case.

Simply put, there are four levels of “commenting” that can be present in code. These are:

  1. shitty, uncommented code that is hard to read
  2. shitty, commented code that is still hard to read, but at least you’ve got a guide. Of course, it’s not a trustworthy guide, so you still have to keep an eye on where you going, but it’s better than nothing.
  3. decent, commented code that reads fairly well. This can probably be read by someone who doesn’t know the language that well. Think of a Shakespearean play annotated in French for Francophiles.
  4. good, “uncommented” code where the comments are restricted to usage guidelines for clients to the class (Javadoc is great for that!) and warning posts (“We use Bar not Foo, ’cause Foo didn’t work”). Note that Level 4 code can’t be read in detail by people who don’t know the language well already; they can probably keep up with the major plot points, however.

In my experience, Level 4 code tends to stay where it is. Level 3 code, however, ends up degrading to Level 2 because the comments get out of date and become untrustworthy. A “good” way to make Level 4 code become Level 3 is to place comments that are too detailed into it.

For people like Chris who are stuck with Level 1 and 2 code, I feel your pain. However, I’m striving for Level 4. The very fact that Level 1 and 2 code exists and is so prevalent is offensive to me.

Good rule of thumb for Java development: if you feel a need to stick in a comment, extract the body of code being commented out into its own private method. Give the method a meaningful name, and turn the one-liner you were going to write into Javadoc for the method.

BTW: Javadoc is wonderful. Good Javadoc provides all the detail a developer needs to be able to use the class from outside. Javadoc shouldn’t be treated as a maintenance guide, however.

Author: Robert Watkins

My name is Robert Watkins. I am a software developer and have been for over 20 years now. I currently work for people, but my opinions here are in no way endorsed by them (which is cool; their opinions aren’t endorsed by me either). My main professional interests are in Java development, using Agile methods, with a historical focus on building web based applications. I’m also a Mac-fan and love my iPhone, which I’m currently learning how to code for. I live and work in Brisbane, Australia, but I grew up in the Northern Territory, and still find Brisbane too cold (after 22 years here). I’m married, with two children and one cat. My politics are socialist in tendency, my religious affiliation is atheist (aka “none of the above”), my attitude is condescending and my moral standing is lying down.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: