Doesn’t anyone ever comment any more? June 26, 2013
Posted by mareserinitatis in computers, research.Tags: commenting, comments, computer, programming
trackback
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.
I also blog at Engineer Blogs, home away from home to some of the best engineering blogs.
No one comments anymore ;-)
I agree with you completely. Rule of thumb: 3 lines of comment for each line of actual code. Otherwise, we might get where we are going – once! But…never again when something changes.
My name is Jac and I approve this message :-)
My second job as software engineer was with a company that outsources engineers to other companies. Working at many different projects where you have to deal with other people’s code pretty much 100% of the time, and are expected to leave code behind that others can work on (and that gets peer-reviewed on an almost daily basis — does anyone do THAT anymore?), is very educational. I follow all those rules you mention, even though I never heard of the book before.
Don’t document HOW IT WORKS; instead document WHAT IT DOES: You can do this by defining formal pre-conditions and post-conditions but those get illegible quickly, so I avoid them except on things that need some sort of high mathematical or logical precision or insane-accurate timing. Just describe what goes in, and what comes out, and let the code itself describe how the input gets converted to the output. Don’t forget to describe side-effects and potential multitasking issues such as re-entrancy.
Don’t repeat the code in the comments: I’ve actually seen source files with no other comments than “x++; // increase x by one”. Obviously those kinds of comments are going to be useless. But I also keep a rule of not repeating comments (just as much as it’s a bad idea to copy and paste code). For example, I write comment headers above each function prototype in my header files, which describe what each function does. I may copy and paste the function prototype from the header file to the source file to write the implementation, but I don’t copy the comment header. While it goes against the general rule of keeping comments together with the code that it applies to, it helps to take a step back from the code and describe what the function is supposed to do, without looking at how it does it. And those who read the header file later will want to see all the descriptions together in one header file, while all the code in the main file doesn’t have the big blobs of function description comments to distract one from understanding HOW things are done.
Don’t explain variables: For historical reasons (think text terminals, character printers and MS-DOS text modes) I like to keep my source files 80 columns wide, at least the comment sections. When I write a function declaration, it starts with one line with just the return type (plus modifiers such as “static”), followed by a comment that describes the return value on the same line. The next line is the function name, which is not commented. The lines after that are the arguments for the function, one line for each argument, where each line has a short comment describing the argument. I align the comments at column 41 so that the left half of the total width can be used for the names of the arguments and the right half for the descriptions. My experience is that whenever that’s not enough to make it clear what is what, there’s often a problem with the architecture: some variables should be combined into a structure or class, or I’m doing too many things in one function and I should split up the function to make it more clear.
I make a point of never using the names of identifiers in my comments. One reason is that I often find myself fixing a problem by changing the name of a variable or argument, and recompiling, so that the compiler tells me via error messages where I the identifier is used. When I’m looking at the code that closely, I don’t look at the comments, so if the comments would mention the old non-renamed identifier, they would quickly go out of sync with the code. Another reason is that this is also a good exercise to make sure that the comments describe WHAT the code does, not HOW it does it. If you can’t describe the code without using the variables, it probably means you’re trying to describe the HOW instead of the WHAT. Which are very difficult to keep apart sometimes.
===Jac