Recently, I was shown this quote. The person who showed it (in a general talk, not to me personally and specifically) is a smart person I respect, so I'm going to leave that person un-named. The authors of the quote, Kernighan and Plauger, are legends of the field. In 1979 (the very same year I was first paid to program) they wrote:
1. If a program is incorrect, it matters little what the documentation says.
2. If documentation does not agree with the code, it is not worth much.
3. Consequently, code must largely document itself. If it cannot, rewrite the code rather than increase the supplementary documentation. Good code needs fewer comments than bad code does.
4. Comments should provide additional information that is not readily obtainable from the code itself. They should never parrot the code.
5. Mnemonic variable names and labels, and a layout that emphasizes logical structure, help make a program self-documenting.
In general, I agree with this. Point 5 is really strong. But when I watched that person I respect walk through this quote I suddenly realized, for the first time in all the times I've seen this, that 1 and 2 are wrong. Really. They're wrong.
Imagine you came across this in a code review:
// Process the first 5 elements
for(i = 0; i <= 5; i++)
{
ProcessElement(i);
}
I hope it's clear that this code actually processes 6 elements. The program is almost certainly incorrect. Perhaps the reason we're reviewing this part of the code is that there is some sort of message in the event log or unprocessed records or incorrect answers that have led us here, suspecting and hoping to find some incorrect code. And look! A comment that disagrees with the code! It's like a giant arrow pointing to the incorrect code. The documentation doesn't agree with the code, and that's great! It makes it really likely that we've found the bug. This sort of thing happens all the time - developers write the correct logic, as agreed in the requirements, into a comment, but sometimes make mechanical errors in representing that logic in code.
If a program is incorrect, comments that represent what the developer hoped or planned or tried to write may be of great value in rendering the program correct (fixing the bug.) If the documentation doesn't agree with the code, with any luck at least one of them is correct.
I still actually agree with the conclusions of the quote, and of those who quote it. Good variable names and function names, well structured code, and written requirements are all more helpful than comments inside the code, as
I've written before. A true conclusion can follow from a false premise. Still, I was initially shocked to find myself disagreeing with these premises, and I wanted to share that insight. And don't feel bad if you leave "translating into English" comments around from time to time. They may surprise you some day.
Kate