FCIWYPSC

Doesn’t anyone ever comment any more? June 26, 2013

While the title above may seem like a complaint about the blog, I am fairly certain that the lack of commentary is probably due to the lack of posting.

Instead, however, I feel like complaining about another issue (one I’ve likely addressed before): lack of comments in code.  One thing that frustrates me about teaching students to program is that they are generally unaware of how important it is to comment your code, particularly when that code is for a research project and may need to be picked up by someone else.

I guess I’m getting old enough that I’ve had several instances of attempting to pick up an old piece of my own code and realizing what a horrible job I did in commenting.  I’m now incredibly thorough when commenting my code so that I’ll be able to go back to it later and understand.

The real issue is, however, that no one ever taught me how to comment code.  It’s something I had to figure out for myself.  The only thing I ever saw was one brief section in Darnell and Margolis’ book.  While I agree with the Do’s they listed, I strongly disagree with a couple of the Don’ts:

• Do not describe how a piece of code achieves its purpose.  This should be obvious from the code itself.
• Do not repeat the code.  Comments should contain additional information that cannot be construed from the code itself.
• Try not to use comments to explain the purpose of variables.  Instead, use meaningful variable names.

While I agree with the second bullet, I’ve learned over time that the first and third are bunk.  Specifically, there is this notion that well-written code should make it obvious as to what is being done.  Maybe if you’re the only person looking at your code, but that’s usually not the case.  As much as we would like to think that meaningful variable names will substitute for explanation in the comments, I’ve found that one person’s meaningful variables may not be that to another person and will probably require significant elaboration.  Further, truly meaningful variable names often need to be rather long, and few people want to take the time to type out names that would be exceptionally clear.  (And then there’s the programmer I knew who used exotic dancer’s names for his variables.  His code was a nightmare to debug.)

The first bullet is the one that really irritates me, however.  I have pulled up code I wrote from a class to use in another class and been completely confused because it had been years since I looked at it.  During the second go-around, I realized there was a chance I may end up using it again, so I started adding things in.  Specifically, I put in the comments that it was algorithm to do linear interpolation.  I even put a reference to the book I got the algorithm from, including page numbers, and what the inputs would need to be (including format requirements) as well as the outputs.  I mentioned what needed to be changed to use the code for other programs.  Finally, I went through and explained what was happening in each step or loop and what the variables meant (e.g., k is a counter, c is the coefficient array).  Without *all* this information, it was impossible to take the code I’d written and modify it for another use without putting in some significant effort.

The reason I went into such elaborate detail (and continue to do so) is that a lot of code, particularly when dealing with algorithms, is almost never intuitive.  If that were intuitive, references like the numerical recipes books would be useless.  (Well, they kind of are, but you know what I mean.)  Therefore, contrary to the advice given above, comment everything, how it works, what your variables mean, etc.  You and anyone else who uses your code later will be very appreciative.