inamerrata

Stewart and Michael have chimed in on whether comments in code are evil or not. Michael reiterates the industry wisdom:

Getting the level of commenting right is hard, especially if you haven’t written much code, or if you are unfamiliar with the domain or the implementation language. But commenting done right can greatly assist yourself and others when you revisit that chunk of code – whether that be to find that heisenbug, or to add new functionality, or even just understand what you were trying to achieve back 3 weeks ago.

I’ve written a reasonable amount of code, and I still find getting the “right” amount of commenting right pretty hard. I’ve even tried a few weird and whacky “commenting” styles, like programming from formal specifications where you specify what you want to achieve and then work from that to the actual code, and literate programming where your primary work is the commentary and the code is scattered about that. Admittedly, I only tried the formal specification stuff at uni, and only for non-real-world problems. In any case, the impression I got from the former was that programming from maths tends to be both harder, and similarly likely to result in mistakes (although hopefully at a more detectable level, of course), and from the latter that explaining things in english doesn’t tend to be that much easier than writing the code (so doing both is twice as much work) and probably causes as much hassle in maintenance as it solves.

On the other hand a benefit from both styles is that when you write code that way, and stick to the formula, you really do feel like you’ve done a good job when you’ve finished. It’s not a quick hack, it’s a professionally prepared piece of software. And beyond a feeling, with both techniques you end up with some assurance that you’ve actually been fairly thorough in dealing with possible gotchas.

In the end though, that’s not enough to overcome the flaws in both techniques, and generally I just end up trying to write clear code, and adding comments when I get confused (either while writing it, or when I come back to it later and find I have trouble remembering what’s going on, or worse, find myself thinking “this is buggy”, changing it, and finding out that while it wasn’t buggy before, it sure is now).

The main issue I have with comments, though, tends to be scoping. Literate programming in particular lets you restructure your code pretty arbitrarily to match your description — if you’ve got a few bits of code scattered through your program that need to be in sync (possibly in spite of good design practices, whatever), you can just put them next to each other along with some comments on what’s going on, and instruct the literate programming tool to put them in the right place later.

There are two other “commenting” variants I’m growing to like. The first is “revision history”. Thanks to the wonders of darcs I’ve become quite enamoured with making a new revision for pretty much every atomic change — what “atomic” means is perhaps hard to explain, but pretty much when I’ve implemented something that compiles, and doesn’t break functionality, I record my changes with a brief comment, and move on. I find that really pretty satisfying, and I’m hopeful that it should also provide a good record for when I get completely confused about why I made some change, which is a good mix. The especially nice thing is that the comments are historical by nature, so it’s not really possible for them to get out of date.

The other variant I like is just writing down thoughts completely separate from the code, whether in blog form, on mailing lists, on a wiki or otherwise. That’s nice in that it helps you cover the complexities of the ideas and put them down in a form that helps you think about things, but that’s easy — since it doesn’t have to deal with all the complexities code does, nor does it have to follow any particular process like “design” usually does. I guess it’s not fair to say I’m increasingly liking that; so much as increasingly leaning towards trying to keep it around and accessible, with blogs and wikis. I’m not sure what will come of that.