Ever now and then I meet people from the “no-comment crowd”. These are developers who claim that detailed comments in source code are a nuisance. The common arguments presented by them are: Well written code is self documenting, therefore, I shouldn’t have to write (detailed) comments. Or even: Comments take up valuable space in my editor window. And the all time favorite: Comments quickly become outdated as the code is being maintained, so what’s the point? This is then usually followed by: Maintaining comments in the source is too time consuming. Calling them the “no-comment crowd” is of course an exaggeration, but it certainly is descriptive.
Personally, I don’t buy any of their arguments.
It is a well known fact that code is much more often read than written. This age old adage holds true in any software development environment, but especially so in an open source project like ours. Every good software engineer knows that – in general – data structures need to be optimized for the most common type of access. Nobody would doubt that. So why have it any different for the source itself? Just like you would spend time on the optimization of a data structure for its most common access pattern, you should spend effort on the optimization of the source itself for its most common access pattern: Read access.
The ferocity of the “no-comment” crowd in their argumentation can be astonishing. Frankly, though, I have to wonder whether developers who balk at thoroughly commenting their code are unprofessional, lazy or both.
Maybe it helps to clarify what kinds of comments we are looking for? For starters, we don’t need a comment in every line. We also don’t need a comment that effectively just reiterates in prose what the code already is telling us. Consequently, constructs like this gem here are really not helpful:
c += 1 # Increase counter
Many in the no-comment crowd list such silly examples as reasons why comments may just as well be avoided. But of course, we are not talking about those types of comments.
Instead, the kind of comments that I am looking for are the ones that explain the rational behind design decisions. The ones that give me a quick summary of what a block of code, a function, a class or file is for and why it is there. Nothing irks me more than to open a source file and the only comment I see at its beginning is the license text rather than a comment that summarizes what the file provides. Nothing is more annoying than seeing a function being called, trying to find out more about it, and being forced to read the whole thing rather than being able to quickly go over a concise summary of it in text.
In general, I think the code should be understandable without having to read code! You know that many IDEs offer the ability to fold away comments. Well, imagine you could fold away all the code: You would only be left with the comments. Would you still be able to understand what your classes and functions are for? Would you still be able to tell why they are there in the first place? That’s a simple test to consider. Notice that I don’t think the comments need to explain what the code does. I’m only talking about the ‘why’, not the ‘how’. The ‘how’ is usually quite well explained by the code. The ‘how’ is actually not all that important when it comes to understanding the program’s structure. Strangely complex algorithms tend to be an exception here, of course. In general, the ‘why’ is much more significant and is exactly what should be commented.
You can see that there is a hierarchy: A block comment before a complex loop or chunk of code on the lowest level. A function header comment on the next level up and a class comment one level higher yet. A file comment and possibly package comment on the highest level. When you change a bit of code around, you know exactly which four comments you have to check to see if you need to to update any comments. And guess what? The higher level ones very rarely need to be updated, unless you do extensive refactoring. Therefore, keeping those comments current and relevant should not take more than a few minutes. Yes, yes, I know: Exceptions exist, but you get the idea.
All of this goes along with Chris’ post about Code as a feature. In that post, he mentions the need not only for code documentation, but also for prettifying the code. I couldn’t agree more and will talk a little bit about that in another post.
Needless to say, our source is not yet perfect in that respect either. But we are trying, and will eventually revisit every module and every file, so that it becomes truly read optimized source code.