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!
Re:You Suck!
jjohn on 2001-12-05T17:22:58
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.
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 cleaned up, I'll likely rip most of the comments out, leave the little pointers, and give an overview at the beginning. (Hell, I may get ambitious and put POD in there, too. You never know.)
