Brandon Savage is writing a series on code improvement using a code example (starting with Peer Review: Taking Code And Making It Better). In other words, it’s about refactoring, which is practically my favorite subject. Although I don’t agree with all of it, it’s mostly good advice. I recommend it.

That said, I do have something important to add. The series is missing the first, most basic rule: Don’t refactor unless you have good automated test coverage (typically with unit tests). And if there are no test, write them before you start refactoring. If you don’t, you’ll make mistakes and get lost in a frustrating bug search, unless you’re very stingy and don’t refactor too much. With test coverage, you have freedom to experiment, to change something and change it back if you don’t like the result. This, above all, is what makes refactoring such a great learning experience.

Some of those who have commented on the post Peer Review: Looking Into Abstraction (Greg Beaver, Jeff Carouth) mention testing and point out the need to inject objects so that they can be replaced with mock objects for testing. This is a wise move, and practically unavoidable in this case. To support refactoring, unit tests need to be run frequently, without accessing outside services (twitter or email in this case) that take time to process.

This means that in this case, it’s actually necessary to refactor a bit before proper unit tests can be implemented. This is what Michael Feathers calls the Legacy Code Dilemma in his book Working Effectively with Legacy Code. Certainly building this dilemma into new code is not a good idea. Make the code unit-testable before it’s too late.

How confused can a discussion get? As confused as the discussion in the comments to Benjamin Eberlei’s Explicit Code requires no comments – Only bad code does. This discussion has a fake identity, and nobody seems to notice. As you can see, the blog post claims to be about code comments, but it isn’t. The example given does not adress the issue of commenting. In the refactored version, Benjamin has not removed the comment from the original, and done nothing (OK, a tiny bit) to replace it with expressive code.  Since the example is irrelevant to the subject matter, it fails to keep the discussion grounded, allowing it to degenerate into dogmatic opinion and subjective speculation.

Also contributing to the confusion is an apparent lack of understanding of the process of refactoring. Refactoring is not a deterministic process, nor is it a strait jacket. You have choice, and you should learn to exercise it judiciously. You take a chunk of code, change it somewhat, and then you decide whether there’s actually been an improvement. If there hasn’t, as many think in this case (and I’m somewhat inclined to agree with them, although Benjamin has great principles and valid points), you have three choices:

1. Refactor further, hoping to arrive at something more satisfactory.
2. Undo the change and try something else.
3. Undo the change and keep the original version if you think that’s the best you can do.

These are the normal choices for those of us who refactor routinely. It happens often enough. Even if you undo the change, it doesn’t necessarily mean you’ve wasted your time. You’ve probably learned something.

In this case, too, there is a chance to learn something worthwhile if you can distance yourself from the noisy confrontation. The most obvious thing to observe is that trying to extract methods from a 6-7 line method is a suicide mission in the circumstances. It’s bound to increase the volume of code a lot, and it’s only natural that the result gets labeled “bloated”. If you do something similar with a longer method, the percentage increase is much less, and you have a chance of not drowning in irrelevant criticism.

Martin Fowler puts it this way:

Technical Debt is a wonderful metaphor developed by Ward Cunningham to help us think about this problem. In this metaphor, doing things the quick and dirty way sets us up with a technical debt, which is similar to a financial debt. Like a financial debt, the technical debt incurs interest payments, which come in the form of the extra effort that we have to do in future development because of the quick and dirty design choice. We can choose to continue paying the interest, or we can pay down the principal by refactoring the quick and dirty design into the better design. Although it costs to pay down the principal, we gain by reduced interest payments in the future.

Brandon’s argument in favor of commenting is perfectly valid, but misses the crux of the matter, since he ignores the option of actually improving the code itself rather than just adding comments.

Let me also comment briefly on Marco Tabini’s reponse:

What I suspect Brandon really means is that the comments are there to illustrate the intentions of the author when those intentions are not immediately made obvious by the code itself.

Yes. And no. There is no absolute boundary, no limit in principle, to how intention-revealing code can be. It’s not necessarily easy in practice, though. As I’ve said before, it’s primarily inline comments that I’m objecting to. The comments I feel a need to write are often at the class level and address the interaction between different classes.

Anyway, arguing about it theoretically is not the way to resolve the issue. Show me some good examples of comments that serve to make code clearer and that supposedly can’t be usefully eliminated by refactoring the code into something more readable. I’ll either admit that you’re right or show you (or at least outline) how to do it differently. I do recognize that even inline comments are useful…occasionally.

(By the way, I seem to have missed Brandon’s comment (Where Comments Are Useful) to my comments considered harmful post last December.)