//Fermat’s Last Comment
There’s an old saw about software documentation:
Documentation is like sex; when it’s good, it’s very, very good, and when it’s bad, it’s better than nothing. –Dick Brandon
Clever quip, to be sure, but it glosses over a big time-sink that maintenance programmers (read: all programmers) have to contend with: wasting time believing in misleading or incorrect comments.
Imagine that you come across a comment like this in some code you’re working on (I’m sure you won’t have to imagine too hard):
// This is borken
What do you do? Do you believe it? How much time would you spend trying to determine which aspect of the relevant code is “borken”? Developers who write comments like this send other developers (and themselves, in a few months when they’ve forgotten it’s their comment) on a wild goose chase trying to figure out if the code is really broken or not.
Perhaps the most famous misleading comment of all time refers to Fermat’s Last Theorem:
If an integer n is greater than 2, then the equation an + bn = cn has no solutions in non-zero integers a, b, and c.
That’s the theorem (which actually predates Fermat), and here was Fermat’s comment about it, jotted hastily (in Latin, originally) in the margins of his copy of Claude-Gaspar Bachet’s translation of the Arithmetica of Diophantus:
“I have a truly marvellous proof of this proposition which this margin is too narrow to contain.”
This sent mathematicians on a wild goose chase for 357 years until Andrew Wiles finally proved the theorem in 1994. Since most of the math required for the proof wasn’t even invented/discovered until the 1960s, it’s widely believed that either Fermat didn’t really have a proof, or his proof was flawed. We’ll never know for sure, since he never bothered to write down or tell anyone what his proof was. Worst. Comment. Ever.
Prior to the 1960s, countless mathematicians doubtless labored in vain, perhaps wasting their entire careers (Wiles himself worked exclusively on the proof for 8 years), trying to recreate Fermat’s “marvellous” proof, oblivious to the fact that they most likely lacked the mathematical tools necessary to derive it, all thanks to that single vague, incorrect comment that he jotted down in the margin.
When I see comments like the one above, I actively delete them. They’re worse than no comment at all, and all they serve to do is waste developer time. First of all, we should always operate under the assumption that any code we’re working on might be broken, so it’s fairly redundant in that regard. Second of all, it’s entirely possible (extremely likely, in some cases) that any broken aspects of the code that the comment was originally referred to might have since been fixed, and the comment is just hanging around for fun.
Finally, if the code really is broken, then file a bug report in your bug tracking system (you do have a bug tracking system, right?) and leave the code where the bug resides without a comment about the bug, for the sake of developers who come along after you fix the bug (and forget to remove your comment). Or, if you must comment in the code, refer to the bug number so people can see the history of the issue. Comments are a terrible way to track issues in your software.
Bad documentation really can be worse than no documentation at all.
September 19th, 2008 at 1:05 pm
[...] on the underlying data set. And it fixed the bug. Nobody really knew why. To be perfectly honest, the documetation for call didn’t really seem like it applied to our problem at all. However, this fixed our bug, so, as a result, AcceptChanges became the first thing that anyone would try when they were having trouble with a dataset and the solution wasn’t obvious. A lot of times, the call didn’t fix the problem, but it didn’t do anything bad, so it would stay in the code, even after the real bug had been fixed. Having code around that doesn’t do anything is pretty bad by itself, nearly as bad as incorrect comments. [...]