Comments and Footnotes

Will I ever stop railing on about comments? I don’t think so. As long as it’s possible to write code in a less than clear manner, people will always be compelled to explain their coding deficiencies. And I will always be compelled to resist.

As a writer, I try to ensure that the main text in a book or article is clear to the reader. Every rare once in a while (perhaps a couple dozen times in a book), I feel compelled to write extra information, something that supplements the text. I do so in the form of a footnote. The footnote provides non-essential information. It’s something that might help add some insights to what I just wrote, perhaps, or a humorous but otherwise distracting note.

My editors would never let me use footnotes to re-explain a passage of text. A coder attempting to salvage bad code with comments is like me adding footnotes to try and explain poorly written text. If the mainline text didn’t explain it well, why should a footnote explain it any better?

Footnotes and comments are ultimately a distraction. Ever try to read a book with footnotes on almost every page (and I’m not talking citations or references)? You may as well be reading two books, in some cases. As writers, we owe it to our readers write more clearly and to minimize these distractions.

 

Comments:

Excellent analogy Jeff.

Today I was asked what I think about assertThat for jUnit4 framework. It brings nothing more than a little bit more verbosity for tests, but won’t help people write better tests. Those , whom tests are of a poor readability and quality will remain the same with a new constructions, too.

Worthless Comments

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.

Comments:

I’m sure someone will read this and go away thinking it says to never add comments.

Jeff said “don’t write comments.”

Atom