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:
MORE: The Best Way to Comment Your Code | Webmonkey | Wired.com.
