I'll get back to the database layer next week. Yesterday I received my copy of a well-known Java magazine in the mail, and it prompted me to write this entry. Usually the things that prompt me to write are not good, and this was no exception.

I was provoked by an article that presents a distillation of design patterns in Java. I wouldn't know how well the article describes the patterns--I couldn't get past the code examples.

Here's a few example pieces of code from the article. Fair use allows me to present this snippet here:

public class Memento {
/** stores the State instance of the Memento */
   private State fState;

   ...

/**
 * This method appends a new item to the collection of items
 */
public void append(Object item) {
...

And on, and on, and on. Ad nauseum. Javadoc comments like this often exist because someone mandates Javadoc on all methods. Never mind that for the append method, the Javadoc tool will supply perfectly sufficient information based off the method signature.

People think that they're being helpful by providing such comments. In fact, they are causing me to waste time. I can't see the code for the clutter of comments. With well-written, well-composed methods, methods fit in one small chunk on the screen and use intention-revealing names. I can understand such code far more rapidly than equivalent code with useless comments.

I've engaged in many discussions in various forums (mostly Yahoo groups) about commenting. There are always people who insist on a larger number of comments than are necessary in a well-written application.

The problem I have is that the people defending excessive comments rarely concede that there are a large number of worthless comments that you should just eliminate. My view is that the majority of comments can be rewritten as better code. Certainly, there will still be the need for comments in your code. I don't deny that.

On one of the lists, maybe the TDD list or the Scrum list, a poster suggested a good example that probably warranted a comment. OK, great. That's one example successfully defended, leaving 99.9999% of all comments unsuccessfully defended.

It's the same argument as with short methods: people will insist that there are legitimate reasons to code 200+ line methods. McConnell does so in Code Complete, which I helped review. Fine, there are (a very few) legitimate reasons to add comments and there are (even fewer) legitimate reasons to concede excessive length in some methods.

But why the argument? Instead of wasting breath defending the rare exception, the larger value is in learning what to do about everything else. Look at every method with a critical eye, and try to find a way to make it shorter or clearer through elimination of comments. That's all I ask.