Comments are one of the most abused programming techniques. I know I’m not the first to say this, but it bears repeating. There are hundreds of ways to misuse comments, and very few ways to use them correctly. In this article I’ll pick on just one way to misuse them: fustian pontificating.
Albert Einstein said something like “things should be made as simple as possible, but no simpler” (it’s unclear what he actually said, so I’m paraphrasing). Einstein’s greatest genius, in fact, was his ability to help ordinary people understand the esoterica of relativity — a subject most physicists would have had trouble explaining to other physicists. Yet he wrote with such simplicity and clarity that I know people who were able to read his work at age ten and grok the essential ideas. This is the mark of true genius: making specialized things accessible to non-specialists.
In “Walden,” Thoreau advised: simplify, simplify, simplify. Emerson is supposed to have responded, “I think one ‘simplify’ would have sufficed.”
In that light, let us examine one of the worst comments I have ever seen in code:
/* * Delayhover effectively creates a phase-shifted version of sfhover * that runs parallel with it. The CSS listens for any of the hover * options: :hover, .sfhover, and .delayhover. There are multiple * checkpoints in the code to prevent asynchronous modification of the * same objects, or at least provide recovery (If a menu gets left open * somehow, a mouseover-mouseout will probably fix it - I've never * seen this, though). * code reference: T__ M_____. */
I was tasked with implementing delays on the drop-down menus, and in about 90 minutes I not only did that, but I took the code down to 84 lines. T.M. had worked on this for I don’t know how many weeks — unsuccessfully. It’s easy to see why: he didn’t understand what the code was doing.