Some people believe code is be self-evident, and, like debuggers, comments in source code are a crutch for the weak developer. I am not one of those people. Commenting code is good. Comments not only help other people understand my code, they also help me understand my code when I re-read it 6 months later.
But sometimes I see comments that make me cringe. Some examples:
/* Check to see if this header file has been included already. */
Any programmer who’s taken Introduction to C 101 should know this construct. If they have not taken the class, they should not be editing this code. So depending on the reader, the comment is either obvious or isn’t nearly helpful enough; either way it’s not useful.
/* This routine implements a spinlock to acquire the lock of a shared resource present in the system. */
If the function name weren’t enough (“foo_spinlock”), the pedant author in me wants to know why all the extra words were deemed important enough to include. After all, effective communication is supposed to be concise, so does that mean there is another function somewhere that acquires a lock that isn’t for a shared resource? Or a shared resource that isn’t present in the system?
Comments like these don’t help the reader, but they do hurt in a few ways. First, they waste the time of the author, who in my experience spends as much time reformatting the whitespace to make it pretty as they spend writing it. This is basic opportunity cost. Second, they decrease code density. The benefit of a large display to a programmer is that they can see more code at once, and that means they don’t have to try to remember what that function returns in case of an error; it’s right in front of them. These days we have wonderful displays with resolutions that can show us lots of code at once, and now we’re filling it with wasted pixels.
What would be better? In the last example, a brief note about how it differs from a normal spinlock would be helpful. For example, “This spinlock uses the legacy ARMv5 swp instruction” could actually help a future reader who’s not too familiar with the ARM architecture, but is trying to figure out why code that worked fine on the old core doesn’t work on the new one. Or information like “Lock instruction sequence copied from Power ISA 2.06″ tells the reader that the existing or missing barrier instructions are probably correct because they came from an authoritative source.
I think that’s really the trick: when writing to communicate, you need to figure out who your audience is. The examples I showed above seemed to assume a lower level of competence in the reader than is useful. If the reader doesn’t know basic C, or doesn’t already know why to use a spinlock, a comment isn’t going to teach them. Instead, you need to assume a base level of competence, and once you do that, your comments will become far more valuable.