The Voynich Manuscript was very poorly commented. Image: Wikimedia

We’ve written before about the value of writing your README before your code, but what about when it comes to the actual code? Terse one-liners? Paragraph-long descriptions? How much is enough and when is it too much?

How to comment code is a perennial subject of debate for programmers, one that developer Zachary Voase recently jumped into, arguing that one of the potential flaws with extensive comments (or any comments really) is that they never seem to get updated when the code changes. “We forget,” writes Voase, “overlooking a comment when changing the fundamental behavior of semantics of the code to which it relates.”

Voase thinks the solution is in our text editors, which typically “gray out” comments, fading then into the background so we can focus on the actual code. We ought to do the opposite, he believes: Make the comments jump out. Looking at the visual examples on Voase’s post makes the argument a bit more compelling. Good text editors have configurable color schemes so it shouldn’t be too hard to give this a try and see if it improves your comments and your code.

Another approach is to treat comments as a narrative. Dave Winer recently mentioned comments in passing, writing about the benefits of using an outliner to handle comments since it makes it easy to show and hide them:

Another thing that works is the idea of code as a weblog. At the top of each part there’s a section where each change is explained. The important thing is that with elision (expand/collapse) comments don’t take up visual space so there’s no penalty for fully explaining the work. Without this ability there’s an impossible trade off between comments and the clarity of comment-free code. No manager wants to penalize developers for commenting their work. With this change, with outlining, that now works.

Winer has an example you can check out if you’d like to see it in practice (and a screenshot of how it looks in the actual editor). Winer is also a proponent of what he calls Narrate Your Work, publishing a running story of his work.

Donald Knuth, author of the seminal book, The Art of Computer Programming, advocated a similar narrative approach with what he called Literate Programming. Literate programming seeks to weave comments and docs out of a “literate” source.

Then there’s the opposite school of thought that says your code should always be so clear and so obvious as to never need comments. See Slashdot for quite a few people advocating this approach, most of whom we suspect have never had to go back and read through their code again years after it was written.

The best way to comment your code is up to you, but whichever path your team decides to follow the best advice is to make sure you take the time to actually have a plan for comments. The most useless comments are haphazardly written, which also makes them unlikely to be updated when the code changes. There are as many approaches as there are programmers; just make sure you actually settle on one and stick with it. Down the road, when it’s time to update that older code you’ll thank yourself.