Via Tony Austin's wonderfully named Notes Tone Unturned blog, I found my way to Write Sweet-Smelling Comments. Despite the name of the article, it's really as much about not commenting as it is about commenting. It talks about a lot of practices that I have known and tried to follow for a long time, though not always as consistently as I should, and it gives much better reasons for those practices than I ever could have thought up. Here's one little snippet from the part of the article that is actually about commenting:
Comments themselves are a sweet smell when they tell you why something was done. When you come across a comment while you're reading code, it should stop you dead in your tracks. The programmer before you felt so compelled to tell you something important—something that couldn't be documented anywhere else—that she left you a comment. Ignore it at your own peril.
I want to add one thing to that. Comments that tell you why something was not done may very well be the sweetest smelling of all. In the life-cycle of projects, the question "why didn't we do it this way?..." (or "why didn't you..." or even "why didn't I...") comes up an awful lot. It's almost inevitable that it will come up in any project that makes it to a release 2.0. Sometimes the reason is remembered. Too often, though, it's not quite fully remembered, or even totally forgotten. I've been there many times, in front of the white board, shirt-sleeves rolled up, a room full of engineers... trying to reconstruct the logic for something I know we considered six months ago but decided not to pursue.
It's rarely written down. Almost never, as a matter of fact. Sometimes there was a very good reason why code wasn't written in a particular way, but without going through a full analysis of the problem it can be very difficult to see. And even though I've been aware of this, and have really almost considered it to be at the level of "a gaping hole" in software engineering practice for almost 20 years, I still find it hard to remember to document negative decisions myself. I think we all have a natural tendency that when we decide against something, we want to move right on to something else. Taking the time to write down the reasons almost never gets priority.
At one point in my career, I made a serious suggestion to my boss that we should use student interns as project "scribes". We'd give them some code to do, but we'd also expect them to sit through design meetings and take copious notes, and pay special attention to the things that we decided not to do. We never did this, though, because (of course) it just wasn't a high enough priority.
One last thing... The StickyMinds site where that article appears looks really interesting. Here's an index of their articles, which I just added to my bookmarks.