On Comments And Code
time to read 5 min | 900 words

There is an interesting discussion about commenting code in the TDD mailing list. I think that we can agree that this comment is uselss:

//Disable the button
btnAdd.Enabled = false;

I don't like commenting in general, and I've been told that it makes my code harder to read and understand. In general I really hate to explain what is happening, even if the code itself is fairly complicated. To take an example, Rhino Mocks has some fairly complex code in it to handle nested method orderring. This is a piece that was very hard to get right (both from design perspective and from coding perspective). It has a single comment explaining the implication of the else case of an if statement.

In all of Rhino Mocks, there are 8 files (out of 56) that contains non (XML / documentation) comments. The comments I have are stuff like:

//I don't bother to check for RepeatableOption.Never because
//this is handled the method recorder
if (repeatableOption == RepeatableOption.Any)

(Where RepeatableOption is an enum with several states, out of which I'm checking only one.)

This one was tricky, though:

//because the expectation doesn't exist, an exception will be thrown
return repository.Replayer.GetRecordedExpectation(proxy, method, args);

Took me a moment to understand what was going there (I'm passing it to the replayer so it would format the appropriate exception message, instead of handling this myself) and it would need debugging to understand why this is needed.

One last one (this is in the part of the code that adds special handling for methods):

//Just to get an error if I make a mistake and try to add a normal
//method to the speical repeat method
Debug.Assert(expectation.RepeatableOption != RepeatableOption.Normal);

The rest of the comments are more in the same style, they are intent revealing and they are far and few between. I was actually surprised to find that I needed the comment to understand what was going on.

Those comments (and the overall thinking behind them) are not meant to explain what the code does, or even how / why it does it. They were written with the explicit assumstion that if you read them you know what you are doing in the codebase. They are there to explain implementation decisions, not how things work. If you need to know, it's not hard to figure out in most cases, since I try to use decriptive class and method names.

I would say that I take the same approach elsewhere in my code. Take the example I posted earlier today:

outputs = new EntitySet<IConnection>(
      delegate(IConnection connection) { Raise(OutputAdded, connection); },
      delegate(IConnection connection) { Raise(OutputRemoved, connection); }
      );

This code is using EntitySet<T> from NHibernate.Generics and anonymous delegates to raise event notifications in the class that create the outputs field. You can't understand what this code does unless you are aware of the things that EntitySet will do for you, or if you don't understand what anonymous delegates are.

But this code doesn't warrant a comment explaining its use, in my opinion. If you need to understand what anonymous delegates are, get a C# 2.0 book. If you need to know what is so special in EntitySet you can check the documentation (assuming you know to search for those :-)).

  The difference in my opinion is that the purpose of comments is to explain the uniqueness of a situation, nor how the code works, even if the code is complex / unusal.

Tweet Share Share 0 comments
Tags: