Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

jjohn (22)

  (email not shown publicly)
AOL IM: taskboy3000 (Add Buddy, Send Message)

Perl hack/Linux buff/OSS junkie.

Journal of jjohn (22)

Wednesday December 05, 2001
09:32 AM

Code Comments: To be Read or Scanned?

[ #1497 ]

Slashdot is running a story about the interview with Joel Spolsky. Avid readers of this journal (me) will remember that I just finished reading Spolsky's book on UI Design. Always one to share his mind, Spolsky's comments have stirred up a tempest in the Slashdot teapot. Much of his comments seemed geared to explaining why Microsoft's competitors failed. He cites Microsoft's coding policy of "never rewrite," which sounds a little hyperbolic to me. What the readers of Slashdot failed to see, apparently, is that the site that interviewed him is a "resource for software marketing, software sales, and software product marketing." Is this the place to get cogent coding tips? No.

However, my attention was drawn to this slashdot comment from one "StaticEngine" who is arguing vehemently for better comments in code. For instance:

Any programmer should be able to look at code by another programmer and pick up on it very quickly, without shaking their head and saying "What the hell were they thinking?"

A bit later:

The best comment I heard was from a friend about a former coworkers code: "It's English with some C++ thrown inbetween the comments."

This all sounds reasonable, right? Who could be against better, more copious comments? Aren't comments the key to understanding someone else's code?

Let me take this point to absurdity, why bother with the code at all? Why not write a paper about the code that explains what's going on. The assumption is that English is easier to understand than a programming language. So once you understand the theory of the code, then modifying it should be easy, right?

There are two reasons why liberal comments aren't effective. The first, oddly enough, comes from Spolsky's book. Users (or programmers here) don't read, they scan. Writing comments to be easily scanned is tricky. After all, scanning works best when the reader has some idea what to look for and the assumption with code comments is that the reader has no clue at all what's going on. If coders are scanning rather than reading, keeping comments small and to the point will be more effective than embedding Moby Dick (or even The Art of Programming) into your module (although quotes from Futurama and LoTR are acceptable).

The second point is probably going to sound elitist, but what the hell: if you can't cook, stay out of the kitchen. Understanding a programming language is the primary job of a programmer. If there's a feature of the language (and not a compiler quirk) you don't understand, get a book and learn. Of course, I still recommend coding in common idioms and avoiding fancy tricks, but code is the definitive guide to understanding the program. You debug code, not comments. I haven't seen a "comment debugger" yet. Comments can lead maintainers to not reading code. This is a sin. You always have to read the code. That last point is so important, I'll say it again:

You always have to read the code.

So comments are fine if used and maintained along with the code. Otherwise, just delete old, inaccurate comments or stick them in your revision control system's log. You are using version control, right?

I suspect there are folks on this system that will disagree with this notion, so flame away!

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • ... but I basically agree. I only write long comments (that is, sentences instead of short phrases) when it is to discuss why the code is doing what it is doing, rather than discussing what it is doing; or, if what it is doing is really really weird, and I want to explain it to myself (or someone else) later on. The latter case is quite rare, and I cannot recall an example of it offhand. The former case happens once or twice a month, maybe.

    Most of my comments are just quick labels saying what something
    • Oh yeah? I've blown sweeter notes out of my ass-aphone!

      I'm in agreement with your clarifications, Pudge-daddy. Once again, you have crystalized my thoughts eloquently.

  • I've kind of fallen into an odd trap. I comment the hell out of the space *just before* something, and then I put little comments in when I figure it's not clear what's where and where's what.

    That is, I explain what's supposed to be going on (mainly to myself so I'll remember later) and then, if the code is particularly long or arduous or uses lots of functions I don't understand, I comment specific lines. I try to avoid that, though.

    Of course, this is code for *me*, at this point. When I get it clea


    You are what you think.