November 15, 2009, 11:19 AM — Harsh words, I know, but I've come to believe it's true.
[ See also: Convincing the Boss to Accept FOSS]
Plone developer Martin Aspeli pointed me at a rather wise blog post in which a C programmer shared three rules he learned the hard way. The lesson that captured Martin's (and my) interest was this:
Good programs do not contain spelling errors or have grammatical mistakes. I think this is probably a result of fractal attention to detail; in great programs things are correct at all levels, down to the periods at the ends of sentences in comments.
"Aw, c'mon! You’re kidding!" You might think that nit-picking like this is beneath you, whereupon I will start pointing out errors in your code. It was embarrassing the first couple times this happened to me.
Programming, whether you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail. Someone who writes software must be a nit-picker, or the code won't work. Surely, you don't need me to cite the number of famous programming failures that were the result of a developer using a comma instead of a period, or random crashes caused by two lines of code in the wrong order?
Perhaps my opinion is colored by my own role as a writer and editor, but I firmly believe that if you can't take the time to learn the syntax rules of English (including "its" versus "it's" and "your" versus "you're"), I don't believe you can be any more conscientious at writing code that follows the rules. If you are sloppy in your comments, I expect sloppiness in the code.
Good programs do not contain spelling errors or have grammatical mistakes. Agree or disagree?(poll)
My premise comes from something a very wise editor taught me, ten years ago (Laton McCartney, in case you're listening: Thanks!). If you can write the deck, he said, you can write the article very easily. If you can't write the deck, you don't understand yet what you have to say, and you shouldn't start writing. (The "deck" is that teaser or paragraph following the headline, which explains what the story is about and cajoles the reader into reading more.) Long-winded "explanations" of the code in the application's comments (that is, the ones that read like excuses), indicate that the developer probably didn't understand what he was doing. Which means that this is a prime candidate to be a bug farm.
Complaining about poor internal documentation is an old practice, but there's a reason that doing it right is important. Your comments are the only way you have to speak to the next person looking at this software (that may be you) about the larger scope of the software, not just this line-or-two. What were you thinking when you wrote this code? Yes, "self-documenting code" is a goal, but it's arrogant to assume that you've achieved it, any more than it's arrogant of me to assume that my words need no editing. (They do. I'm happiest when I have an editor.)
Another common problem in comment ugliness is developers who update the code and don't update the comments; as one consultant pointed out, comments aren't tested. But doesn't that show a lack of attention to detail, too? Anytime you aren't paying full attention, you're apt to drop a logic bit.
Need a few examples?
From an explanation of a design choice. ("Yes, I can guess what was probably intended," wrote the programmer who showed me this example. "But therein lies the problem: I have to guess.")
"... questions designed to illicit a discussion..."
Here's an actual line of code with comment. Note how the comment highlights the spelling error. Not to mention that the comment tells you the programmer didn't have a clue of what he was doing in the first place. Especially since it shouldn't have been "finished" in that block of code; in that application, it should have tested against "complete".
if item.getState() == 'finsihed': #is this correct?
Yes, I allow for some exceptions. If English is not your first language, then it's possible that the comments you leave in your code will demonstrate any discomfort you feel in writing English. However, I haven't personally found this to be true. As many Americans have learned, "foreigners'" English skills are typically much better than our own. The developers I know whose English language skills are awkward are aware of it and they go to great lengths to ensure that an English speaker edits their documentation.
I won't go into code and comment indentation; that's a religious issue. But I've met developers who feel as strongly about "ugly" code formatting as I do about ugly grammar.
Modern development environments arguably have made it possible for developers to be sloppier without ill effect; a drag-and-drop interface might let you create a quick-and-dirty application (more dirty than quick, I fear) with fewer terrible side effects than back when software was typically written in Assembly language. Somehow, however, I can't see "I can be sloppy" as a true advantage.
The "ugly" comment rule is just as true for internal business applications as it is for open source software. But FOSS developers need to pay more attention to it for two reasons. First, in a regular office, you very likely can find the programmer of the offending code and question him (or wallop him, if it was that bad). Also, in the open source community, more people look at the code and need to understand it.
However, when I suggested to several developers that "if the comments are ugly, the code is ugly," many disagreed with me. You might, too. I'm interested in learning why, so I created a poll (let's see what everyone thinks!) and I invite you to leave a comment.
You probably should follow me on Twitter. Because, y'know, you just should.
