Here’s a quote from the comments of someone else’s blog entry exploring how a number of open source projects tend to shy away from documentation:
“…you’re ignoring cultural issues with coding. In an extreme programming project, for example, comments are generally considered to be a bad thing, even the “helpful” ones. But that’s because the reaction of an XP developer, upon seeing a comment, is, “How can I change the code to better express its ideas so that the comment is not necessary.” Because it avoids comment obsolescence, this is a better approach than using comments to describe code, yet it would be penalized by your count.”
I can’t tell you how much trouble the idea of “commentless code” has caused me in the last few years. The idea that code can be self-documenting is only applicable in the most concrete and straightfoward systems imaginable, and the XP belief that code with comments needs to be “refactored” to be more obvious, tends to lead to systems that purposefully shy away from anything deemed too “complex”. In other words, in a true XP environment any code that requires any level of explanation must be “refactored” to become more obvious, more “self-documenting”.
Not having to explain yourself might provide a illusory feeling of agility to developers who can’t bother putting nouns in front of verbs, but we’re talking about logic, and, very often, logic needs some exposition. A small, elegant general proof can require pages and pages or justification and explanation, and code is no different. Code without documentation contains little in the way of justification (“we did this because of X”), it contains little in the way of direction, and almost always tends to frustrate and confuse the next batch of developers to assume control of a codebase. The two examples of comment-less code I’ve witnessed over the past few years have both been somewhat of a disaster. In one case, an organization with very rapid turnover continues to wonder about the motivation behind an ornate multilevel mess, and, in the other case, the codebase was useless unless the documentation averse engineer was sitting right next to you, walking you through every line.
If you are currently working for some dictatorial XP zealot, resist by writing comments, pages and pages of comments. Dare to explain yourself. At least provide some hints for the poor sap that needs to take over your mess in a couple years.