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.)

As one of the critics expressed it:

No, comments are there to comment. Period.
That has nothing to do with how good is your code.
You can write perfectly clean code and add good comments to it. Nothing wrong with that.

This is one of those ideas that seem obviously true in theory, but fail to work in practice. The reason is that comments get out of sync with the code. The comments rot, or rather, their meaning does. They become more and more misleading as the code gets changed and the comments are not adequately updated.

Let me give you an example. But first, I want to make it clear that I don’t think code comments are always a bad thing. Sometimes, they are necessary. But much less often than people think.

API documentation is often indispensible, but that’s really a different matter. When API documentation is generated from comments in front of each method, the primary purpose is to explain how the code can be used, not how it works. In fact, you might say they are code comments only in a syntactical sense.

On to the example. One of the comments to my blog post presented a code snippet that illustrates my point well. It’s supposed to be a example of a useful inline comment in code.

// first handle the case where no records were found
if ($records == 0) {
    return false;
}

Is this really an case of good commenting? I don’t think so. If it’s hard to understand that $records == 0 means that no records were found, we can change the code to make it easier. The simplest way to do it is to rename the variable to something like $numberOfRecordsFound or $numRecordsFound. Or extract a method. But typically, it’s possible and preferable to avoid this kind of check altogether.

Anyway, the comment is unnecessary. But as I only realized a while later, it’s also misleading. Does the code “handle the case where no records were found”? No, it leaves it to the calling function to handle the case. The one line that returns false is not handling anything, it’s just passing a message.

So the comment is already misleading, never mind what will happen when someone changes the code and neglects to update the comment. For example, let’s say the next programmer to work on this code is in hurry to fix a bug. Now maybe the code will look like this:

// first handle the case where no records were found
if ($records == 0 && $state == ACTIVE) {
    return false;
}

The programmer wonders briefly whether the comment is still fully appropriate, is unsure, and decides to do nothing about it (or postpones the decision and forgets about it). Now, perhaps (we can’t quite tell without the full context), the comment is even more misleading.

In the next round, yet another programmer comes along, makes some more code changes and wonders: “Should I update the comment? It looks all wrong to me, but it was probably written by someone with deeper insignt into the code. Better leave it alone.”

The code would have been better off without the comment, but no one wants to delete it, especially since they have been told that comments are so important. It’s a downward spiral: the code changes make the comments misleading less chance that they will

Comments that lie are worse than no comments, and in practice they tend to big liars.

Implementing automated tests by using Seleniums API methods has several drawbacks. Selenium is great for what it does, providing a generic framework for testing a generic application. Using the Testing_SeleniumDSL framework, I will show you how to create your own Domain Specific Language (DSL), which would allow you to write tests in the language of your business rather than in Seleniums language.

I’m quite impressed by the examples he presents, such as:

$this->assertThat($form->hasSelect(withName('statusConfirm'))->hasValues(),
    array('Yes','No'));

This is truly expressive, readable code. I’ve refactored web test code in this direction many times, but I admit I never got quite this far.

The DSL is planned as an open source release. It would be interesting to try something similar for the SimpleTest web tester, which is my favorite for testing web interfaces without too much JavaScript. (Based on the paparrazzi principle.)

The analogy between cleaning and refactoring is useful for making the non-developers understand that refactoring is absolutely necessary. But beyond this pragmatic similarity, are the two really similar in deep and meaningful ways? I don’t think so. Refactoring is not unskilled labor. It’s a task that both requires and builds design skill and experience. While anyone can see that a floor is dirty, identifying code smells is non-obvious, tricky and demanding. This is true even of the simplest code smell, duplicated code. Although spotting code duplication is sometimes easy, at other times, the duplication is too subtle to be easily identifable. When you clean a floor, the goal is well-defined and easy to visualize. When refactoring, you may know what you’re aiming for at each small step, but just a few moves further ahead you may end up with a structure you hadn’t imagined.