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