Livable code, Embrace the Practical Mess

Part one

John HotterbeekxSr. Software Engineer

[the following piece originally appeared as the first half of a post on]

John Hotterbeekx is a senior software engineer who’s been with us  for eight years already! He’s always been interested in the clean code principles and in the first of this two-part blog post, John shares his experiences using the clean code principles and discusses the types of clean coders. In the second part, he explains how to get to the livable code yourself.


Let me start off with the fact that I’ve been interested in the clean code principles for quite some time: I think it’s very important to keep these principles in mind while developing software. Other people should be able to read and understand your code without a decipher ring and you should not have to move mountains to add a simple feature. With this, I’ve embraced the words from our Uncle Bob and tried to bring this into practice. That was, until my last personal project where I found myself wondering, “What can I do to clean this code even more?”. It felt like cleanliness itself had become somewhat of a burden, and it was taking the enjoyment out of just writing the code because I felt it had to be as clean as possible. Was I taking it too far?

The first extreme, the hoarder

In our career we’ll all come across the two extremes of cleanliness in the code bases we will work with. Let’s start off with the most common of all, the hoarder code base. You know what I mean, that one project: where even by speaking its name you’ll see a tear running down the cheek of your fellow developers; where you open a file, just to add a simple input field to a page and three hours later it feels like the code is swallowing you whole. It’s a mess, there are classes of more than a thousand lines, and changing one property in page one breaks pages five, six and eight and you have no idea why. Your feature or fix will be slapped in the code, maybe some duct tape is placed over it just to keep it in place and even though you know you’ve probably made the code even worse, you close the file as fast as you can and deploy it, hoping to never have to touch it again. How do you think this happens? Most people will probably say laziness. But it’s not, at least in most cases. This cluttering happens one small decision at a time. You start off with a nice clean class and just add a small thing here. It doesn’t really belong here, but it’s easy this way. The next person sees this and changes another small thing, there was already something in the class that didn’t really belong there, and now there are several things in there that don’t belong. You see where this is going?

The second extreme, the showroom

This is the other extreme, that not everybody will recognize as fast as the other extreme, but it is there. I like to call this code the showroom code base. If you dig into your memory you’ll find them, those projects where you kept cleaning and cleaning, making the code better. Adding some abstractions, a pattern here, another one there, some more layers. Do I see a duplicate line there? Let’s create a base class. More than 20 lines in the class? That has to be split up! This feels great when you are starting out, and you’ll be able to keep this up for quite a while but then a new guy has to work on the project, or you have to switch to another project for a while. You come back and want to add that same simple input field. Knowing that the code is cleanliness itself you open the class, to find that you should go a layer deeper since it’s not really the responsibility of that class. In the next one you go deeper as well, and deeper, and deeper, oh a factory. You just have to figure out which direction you should go and two hours later you think you have found it. But you can’t just add this here, because it will appear in several places, you need to abstract it further only to find that when creating the abstraction, other implementations need even more abstraction. What has happened here? The code becomes too clean, it’s just like a showroom home, like in one of those catalogues ready to sell. It looks great, but if you look closely, it’s not practical to use. There is no place to put your coat, your drink, the TV and is that even a full-size couch? But it does look great. This is mainly caused by software design books, articles, and blogs that show us the unrealistically clean code and give us the wrong goal. Code that follows all the rules and is perfectly consistent and abstracted is unattainable unless there is nobody living there.

What’s in between? Livable code

When you take the analogies I have used, between a hoarded living space and a showroom living space, there is the living space that’s actually being lived in, the livable space. The beautifully decorated room, with some mess. It’s might not be as pretty as the showroom, but at least there is room for your TV with a console and a couch that you can sit on properly. The same thing goes for code: in between these two extremes is the livable code. There is some duplicate code in there, some classes are a little big, but their names tell you just what they do and it’s pretty easy to find your way in the code. There may be some places where it’s still a mess, but slowly and surely we are changing that mess to make it better. This is the code base we should embrace. This is the code base that feels like home. This is the code base we love to work in!

Look out for part two of this blog where John explains how to reach the livable code yourself.

Related content

How to use data to build the workplace of the future