Sunday, June 19, 2011

About comments

Okay, comments are one of the most obscure subject in programming. Yes, obscure, I really mean it.

Why ? Probably because there is no good way to use comments in your code. As I remember, in my student days, teachers explain to us that comments are mandatory, that a good source code is made up of more comments line than code line and so on, but none explains what to put in that damn comments.

Of course, there's the running joke on the "increments i" comment, but that's all.

As I'm now on the other side (yeah, I'm teaching programming), it was obvious that I should not make same mistake. But, how on earth should I explain to student how to comment their code, if I still don't know how myself ?

So, for some times I was doing like my teachers did, which means I avoided the subject !

But, then I ran into some text from Rob Pike (about programming in general) and he makes a strange remark: "I tend to err on the side of eliminating comments, for several reasons." (Rob Pike: Notes on Programming in C) This sentence strike me first, but then I realize that it was the good way to manage comments.

Most of the time comments are useless !

Why ? Just because the code is probably the best way to explain what you are trying to do !

So, should we always avoid comments ? Of course not, but we should use wisely ! The first question is "why" (not when or how !):

  • You need comments to explain how to use your code
  • You need comments to describe where to find some piece of code
  • Sometimes, you need comments to explain a trick or an unusual hack
  • You may need comments to track down modifications, but fixes and ugly workarounds
Other comments are just a waste of time.

So, the first and most important comments are what we should call "interface comments", that is comments in header files or before definitions. Those comments will explain: what the function does, how to call it, and what constraints should verified (pre-conditions, post-conditions and invariant.)

You can also put comments in front of files to explain globally how things work. Take for example what you found in a lot of driver's source files: a global explanation on how the device works and what are the specific points.

Then you can sometimes explain some tricks. But be careful, those comments are often less informative than it seems to be ! Explaining, using natural language, what a complex piece of code is doing is harder than writing the code itself. Most of the time, the reader will be able to understand what your doing by reading the code, if not, he has nothing to do here ...

A good example of bad comments can be found in the source files of GNU C library. Take a look at the definition of the  strlen function. The function is quite simple, the glibc version is little bit trickier than usual (read word by word rather than byte by byte) but no so complex. The trickiest part is the detection of the final NULL char inside a whole word. Ok, this can require some explanation, but the comments double fail this job: first, the text is less understandable than the code, second, the comments are obfuscating the reading of the code by breaking it into parts separated by big pieces of text ! And, the actual version is more readable than the first one I see.

So, most of the time don't even try to make a comment on your tricks, or put it outside of the code !

Commenting changes and corrections are the most difficult part. These comments are very useful, but they tend to grow bigger than they should be. You have several way to do it, but I found none very satisfactory. First, you can only rely on your version control system's log, in fact, you are probably already doing it, the only issue is that it very hard to find out the history of a specific piece of code (not a whole file, but a single function or data structure.) You can also add it to the code itself, but again, if you put it in front of the file, you loose the connection with the concerned code and if you put it right to the code, it will break the natural flow of your source code.

It would have been nice to have a clever integration of source files, version control and revision logs, but I haven't found such a tool.

So, as a conclusion, I will use some striking mantra (remember, you can't trust maxim !)
Comments are nothing but noise !