Commenting Source Code

I read on another blog today an argument against putting comments in source code. I’ve heard arguments of this nature before, and I’ve had fervent debates with other programmers on this topic.

My opinion is quite simple: comment your code. I always get the sentiment that those who oppose the practice of commenting have never been tasked with maintaining a very large repository of undocumented code written by someone else. But it isn’t just for the programmers that will have to deal with your code in the future that you ought to comment – it’s also for yourself.

If you have a program that’s in the thousands of lines of code or more, you’re not going to remember the particulars of its operation in a few years from now. You’re not going to remember that you set a flag for your TCP/IP initialization function on line 853 that made the socket read calls non-blocking.

A lack of comments wastes more time than it saves. For all those seconds a programmer saved by not documenting their logic, another programmer spends hours tracing through source code trying to figure out where a certain event happens. Or figuring out why a block of code does a particular action.

Take the code I was working on the other day. There was no comments and I had about twenty lines of cryptic bit-wise operations. I eventually figured out that it was to convert 24-bit big-endian two’s complement integers into 32-bit little-endian two’s complement integers. The author had chosen a very… interesting… approach to the conversion. All this time I spent on the problem could have been saved had the author bothered to include a single explanatory sentence in English.

Many opponents of commenting hold this view that the code should be readable on its own. That’s possible when you deal with small projects. But when you deal with multiple source files and thousands of lines of code, being told that you should decipher through all of that simply to change a bit somewhere is a ridiculous proposition.

This all comes back to the fact that a programming language is not a natural language. It is not an effective communicator for what it is doing. Whereas in English, one might say that “we look for the first bit to see if it’s a negative integer”, in a programming language it might simply be “& 0x80 == 0x80”.

Good, well written code is always enhanced with good, well written comments.
— Bo

If you write small programs that won’t ever be looked at in the future, you don’t need to comment. However, if you write code that either you, or someone else, will be forced to revisit – then comment. There is no excuse for this. It takes only seconds of your time for every X lines of code, and if you don’t have time for that, what does that say about the amount of time you have to think through what you’re coding down?