Earlier this week, Graham Lee wrote an opinion piece about what separates a good code comment from a bad one. It’s thoughtful and well-written, with plenty of examples and some excerpts from the relevant literature.
I must admit that my philosophy on code commenting has changed quite a bit over the years, as both I and my projects have gotten more sophisticated. (Well, the projects have gotten more sophisticated; I think I’ve just gotten older.)
When I was just starting out, commenting code seemed like a boring waste of time. Why on Earth would I spendwaste valuable time putting in comments when it was perfectly clear what the code was doing? Besides, I wrote the code, and I’d surely be the only one ever asked to maintain it, so there’s little point.
Of course, this was also a time in my career when coding projects numbered maybe into the hundreds of lines. So, arguably, there may have been some merit in the notion that comments wouldn’t have added a lot of value.
Then came the time when I needed to ACTUALLY go back and revise some code I had written years earlier. Yeesh. If there was ever a way to feel you had amnesia, this was it. I was looking at code I had written — I knew I had written it — but couldn’t recognize it for the life of me. I had gotten so much better in the language and the algorithmic design that I recognized the old code for what it was: a mess. And a virtually uncommented-one at that.
If losing a hard drive full of data is what makes most people fervent backer-uppers, getting baffled by my own historical code was what drove me to commenting. And in a multi-person team, it’s essential, since comments can also document required parameters and their meanings, and actions that need to be picked up by someone else. Heck, I even use comments to myself in the code to remind myself where I stopped work one day and where I need to pick up the next.
Beyond the act of commenting, though, there are some key differences between good ones and bad ones. But I’ll let Graham Lee pick up that ball. He’s done a good job of it in his article. Worth a read!