Wednesday, May 13, 2009

Can a boy scout be too eager?

The software craftsman movement tells us that as professionals we should strive to do our best. Among other things we should strive to write the cleanest code we can. One of the ways do that is to adopt the so-called Boy Scout Rule. When adapted to software development the Boy Scout Rule goes as follows:

Always leave the code cleaner than you found it

So what does that mean? Well, if I was to simply follow the rule exactly as stated I would always do my best to clean up all the code I came by as much as I could. That leaves me with (at least :-) two questions: Should I really clean up all the code I come across (no), and should I always clean the code as much as I possibly can (no, again). The following paragraphs gives you my thoughts on each question:

What should I clean?
Cleaning everything I come across obviously is not going to get me far: If I use open source library X in a project should I start by cleaning up all the code in X as much as I can? -I think not. Although X might very well be a good and sound project it will inevitably contain a considerable amount of not quite clean or downright dirty code. -Every code base of any significant size does.
So always cleaning up code before using it, would leave me stuck cleaning other peoples working code, while I could have started on my actual project. Not good.
Right, so if I am not going to clean up all the code I meet on my path, then where should I draw the line? I draw the line at code I change: If I change a line of code in a method, I clean up that method, and possibly the class containing it. If I change a couple of methods in class I clean up that class. If I make changes to a couple of interrelated classes I clean up their interaction.

How clean should it become?
In his Clean Code book Uncle Bob goes through an example of cleaning up a class from JUnit (chapter 15). The end result is very nice, and definitely cleaner than the original. But the original was actually pretty good in the first place. Even Uncle Bob thinks so: He writes: "[...] you'll find it [the JUnit code] to be nicely partitioned, reasonably expressive, and even simple in structure". And I agree, the original code is more than decent.
Throughout the chapter Uncle Bob carries on to clean up that code, and ends up with something very different from the original. The chapter ends with the following conclusion: "And so we have satisfied the Boy Scout Rule". I don't agree. Or rather, I think he has over-satisfied the Boy Scout Rule: The code is changed so much that it could be hard to recognize for the original author, which I think is a problem.
The original authors are (in my experience) more than likely to return to the code later. If they can recognize the code, they will probably be able do whatever fix they are there to do pretty quickly. If they cannot recognize the code their work will be a lot slower - even if the new code is cleaner. I think this consideration often outweighs the need to clean up code as much as possible.
Rather I think the quest for clean code should be an incremental endeavour where the code is left a little cleaner each time it's changed, but never changed radically in one go. Over time this incremental cleaning might very well change the code to the point of being unrecognizable to the original authors, but only if they have not followed or taken part in the incremental clean up. In that case they have effectively stopped particpating in the maintainance of the code, so slowing them down is not such a big deal.

We should, in general, strive for writing the cleanest code we can. The Boy Scout Rule helps us do exactly that, but don't be too eager: Don't clean up code you are not already changing for other reasons. And don't clean up code to the point of being unrecognizable. 


  1. The Boy Scout Rule simply states that you leave the campground cleaner than you found it. That means if you pick up the cans in the fire pit and carry them out with you, you've satisifed the rule. It doesn't say anything about sweeping up all the dirt and mopping the rock layer beneath it.

    Each craftsman will interpret it differently. While I don't think anyone seriously thinks cleaning the open source library you use is beneficial, some, like Uncle Bob perhaps, might clean a whole subsystem. Others might clean the classes actually changed. Others might just clean the function just changed.

    Just leave it cleaner than you found it. How much cleaner is up to you and the customer.

  2. There is some further discussion on this subject in a thread at the software craftsmanship google group: