Coding and Comments

Some recent Twitter posts by Adam Keys got me thinking about the role of comments in code. Good and consistent coding style that reflects a solid development philosophy helps eliminate the need for many kinds of comments. Capturing requirements in a formal-ish way (through the use of techniques like Behavior and Domain Driven Design) eliminates even more. If important requirements can be captured formally in a "live"[1] way, they generally should be.

But (a) you're not always in a situation where formal-ish requirements capture is possible and (b) there is some information that can't be captured formally.

It's clear what needs to be done in the long term about (a), but in the mean time if you're going to have static text, it's good to have it as close to the code as possible. Comments let you do that.

It's not so clear what can be done about (b). Even if you've read the code and grok it 100%, there are situations ("Although it's irrational, as of Oct. 18 2005, the accounting department insists we use HTTP basic auth without SSL") in which the code is not enough. Anything to do with people and their motivations, really.

So, imagine yourself as a slightly-less-clever-than-you-think-you-are future reader of your own code. Imagine that you're generally familiar with the application, have read the code in some detail, and understand the development philosophy (hopefully) baked in throughout the system. If you're still thinking "WTF?!" then put in a comment. If it takes a full paragraph to explain the awful circumstances that led you write something impenetrable, then do it. Your future self will thank you.

[1] In post-Singularity world, code executes you. Until then, you can't really refactor, trace, test or formally analyze static natural-language text like comments or (shudder) external requirements docs. Natural language isn't "live".