In previous posts I’ve mentioned Sandi Metz’s TRUE heuristic for judging code quality, but I’ve never delivered on my promise to really dive into it. This week I’ll finally start that dive.
TRUE is an acronym that stands for:
If code meets those four criteria then it is well designed. Let’s dig into each element and find out what they mean.
It is easy to see the code’s function and the effect of a change
These two methods do the same thing:
The opaque method has all the hallmarks of hard-to-understand code. Magic numbers, methods named after jokes, constants with useless names.
The transparent method, while not the Best Method Ever, is at least understandable. You can see the effect of changing
loyalty_bonus for example. You can see that you are telling accounting about a change, instead of wondering what the heck a monkey kick is.
A change takes effort reasonable for its complexity
Again, two methods that do the same thing:
Changing a salutation should be easy. But changing it in the Unreasonable method would require you to alter a ternary to something worse. In the reasonable method you can pass in any salutation you want or use the basic salutation.
The code can be used in other contexts
square_number is syntactic sugar that can only do one thing. Great if you need to square a bunch of numbers, I guess, but unusable beyond that.
power will work in greater number of contexts.
The code serves as an example of the kind of code you want
Contrived? Sure. But google “monkey patch Array” and marvel at the weird stuff people want to patch into to Array. In the unworthy example we have globally changed the behavior of the
first method. We don’t want people taking this code as an example and continuing the tradition.
At least the exemplary example contains the damage to this one class. I’d much rather see this approach than the first one.
Here’s what I said when I first introduced TRUE
Note that all of Sandi’s criteria are about modifying the code. Each point talks about the effort and effect of changes to your existing code. You can’t look at a piece of static code and say whether or not it is TRUE; you have to think in the context of code maintenance, which is when design is most important.
Which, thinking about it more, isn’t exactly correct. You can look at static code and judge its TRUEness. My opaque code example above is opaque whether or not I need to change it. I can make a choice when coding to write exemplary methods that are not tightly-bound to a single problem. You should try to write TRUE code now, but you might find out that you missed the mark when it comes time to change the code.
Next week we’re going to write some code and then refactor it using the TRUE heuristic. All so we can write some slightly-dirty rhymes.
My newsletter is not dirty, but it is quite smelly. Last week was the second entry in the Catalog of Smells: Long Method. This week we’ll add a new smell to our collection. You can sign-up for the newsletter, check out previous issues or enjoy a nice beverage of your choice. Comments/feedback/&c. welcome on twitter, GitHub or firstname.lastname@example.org