A few months ago, I talked about an argument I had at work, where a coworker who sipped freely from the heady koolaid of eXtreme Programming espoused his belief, straight from the XP canon, that code with comments is automatically bad code. He said if he downloads an open source package and sees comments in the code, he rejected using it immediately because he knew it was bad. I took the counter-argument, as I found this a nutty belief. Good code is good code and bad code is bad code, and presense or absence of comments cannot turn either one into the other.
Now I find this essay on code comments and expected readers to be very enlightening. He points out that believing the code should stand on its own and be self-documenting doesn’t hold for a general case of any possible reader. What if the language is not their primary one, and what is an obvious idiom to you is not obvious to them? What about the common case where a junior programmer of limited experience is the person maintaining this code base down the line and cannot make the automatic inferences of the experienced original developer?
This all gets to a lot of what bugs me about XP. Just like fundamentalists in a religion can put you off of a philosphy that you don’t intrinsically dislike, so do many XP accolytes put me off the ideas. Taken one by one, most of the pieces make perfect sense. Unit test everything freakishly often; right on. Do work in small pieces, with much input from others early on in the process; yes indeed. Build continuously and find out integration issues as early as possible with minimum surpise; check. Left to my own devices, I do most of this anyway. Why then does XP turn me off so much? I think it is the cowboy maverick attitude of the vocal supporters. The ones I deal with have a “This is how it will be, and if you can’t hang with it then you aren’t good enough to play in this game” chip on their shoulder. Working as one member of a multi-person group as a team effort. Deciding that you are too good to make it easier on other members is a horrible prima donna attitude. One of the ways to make it easy is by communicating to any others who touch your code whatever information they will need, rather than making them spend the time to gut it out themselves. If you take a non-standard approach to something because the standard doesn’t work, put that in the comments. Otherwise, no one else will understand why you did something weird. At the very least, filling out the Javadoc comments about expected inputs and other gotchas should be a minimum so that you can generate an API doc from it.
In the meantime, any code religion that says that a comment in a code lowers the value of the code is one that I can’t believe in. That’s just the way it is.
