No Comment

Comments in your code are bad. There - I went ahead and said it. If you need to comment the majority of your code you're doing something wrong.

Now, before I get attacked by an angry lynch mob of pitchfork wielding programmers who have just spent the last week digging through a uncommented pile of junk code let me put in a couple of caveats and go over a little history. First of all, I'm talking about code along the lines of something written for Web development - higher level stuff that's usually relatively straightforward (or should be). I'm not talking about device driver code in the Linux Kernel.

Now jump back 15 years ago - When CGI on the Web was just starting to hit it's stride, and there was a good chance that you were writing in C or C++, and going through the occasional loop construct:

 for(k=0;k<<len;k++) *ptr++ = (int) *ptr2++ * 100;

I've seen a lot of code written that way, and short variable names, pointer arithmetic and i,j,k iterators were pretty much par for the course.

These days (and in a different language), I'd write the above something like the following:

prices_in_cents = prices.map { |price| (price * 100).to_i )

Both of these snippets (on in C one in Ruby) do more or less the same thing. I would probably want a comment before the first one, but an extra comment in front of the second one just takes up space.

The newest round of languages have become much more expressive and thus can be much more compact, and so you can do a lot more in fewer lines of code and still do it more clearly. This and a better set of tools (e.g. autocomplete) has sort of made it ok for developers to start using longer and more expressive variable and method names - if you only need to type a variable a couple of times and your IDE types most of the word for you anyway, a 40 character method name is much_easier_to_understand (vs. _metu).

All this has gotten me to the point where most of the time, I would really rather the developer spend whatever time they would have spent on the comments on improving the readability of or refactoring the actual code.

When written with an eye towards correctly using the expressiveness of the language and keeping methods small and to the point, I like code better than comments, especially as many programmers don't write expressive high level comments but rather just end up writing some pseudo-code to comment their own code. For the C snippet above, I'd love to see a comment like:

/* Create a list of prices in cents (rather than dollars) */

but chances are, the comment will be something like:

/* Go over each element of ptr2, multiply it by 100 and put it in ptr */

That second one doesn't tell me anything the code doesn't - assuming you understand the programming language you're reading - so there's not a huge advantage to having that comment there anyway.

A couple more caveats - this is only for well-written code in a newer language that an average programmer could understand in a glance. If it's anything more complicated than that or you're writing closer to the metal in a lower level language - comment away, but ask yourself first if the code be made clearly with some extra work instead. The next person in is going to primarily be changing the code, not the comments.

Clarifying the code directly circumvents the other major issue with comments, that they can be out of date while the code never can be (or you have bigger issues). This doesn't happen that much, but comments about the specific blocks or lines of functionality are the ones that are most likely to be out of date as bug fixes and modifications are likely to be verified before a developer comes back and spends time to update the comment, and let's be honest, they (and you) will sometimes forget.

Last caveat - I'm talking about code comments here, not comments used to generate documentation (like RDoc or pydoc), those are fantastic ways to generate useful documentation for a project that are much more likely to stay up to date given their proximity to the code they are discussing. Also As these comments are generally at the method and class level, they force the developer to think about the abstraction created by the code as opposed to the code itself and so will tend to be more useful. That being said, I have also seen:

# send an order given and order id and a cart
def send_order(order_id,cart)

So your mileage may vary.

So there you have it - I'd rather see good, compact, refactored code without comments than one-and-done code and some quickly written comments. Not that controversial after all, right?

Update 9/14: Before I get skewered for saying something idiotically obvious (i.e. "Bad comments are bad; film at 11."  ) - this post was written in response to an angry email I got after delivering a project a couple months back, with full Rdoc,but, I was told a lack of comments in the code...So yes, many people subscribe to the philosophy of limiting code comments and focusing on refactoring, but at many levels (especially the corporate level), there is still an expectation of a large number of comments in your code.

Update 9/23: Of course,  "self-documenting" code can be done wrong as well