Livable code, Embrace the Practical Mess

Part two: How to get to the livable code yourself.

John HotterbeekxSr. Software Engineer

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

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


How to get there

Although most projects tend to go more to the hoarder extreme then the showroom extreme, the steps to get to the code base you want is the same. Following the steps below will slowly but surely move your code base to a healthy livable place:

  1. Don’t make it worse!
    When you are editing bad code, don’t take the easy way out and make it even worse. You don’t need to fix the whole file, just make sure it doesn’t get worse. This could go both ways; you could make the clutter worse, or you could create more (unnecessary) layers if you’re already leaning towards a too clean code base.
  2. Improvement over consistency
    Five books on a pile and one on the shelf is better than all six in a pile. Every time the code is touched, someone can move one of the books to the shelf. If you wait to move all books at once, it’s not going to happen. This may seem hard for a lot of people since a lot of clean coding articles value consistency very much. But remember, the image that these articles give you is that of a showroom code. While that beautiful code looks like a picture, we need some clutter to feel comfortable. If you look at it practically, having five classes that are a mess and one that is like it should be, is better than having six messy classes.
  3. Inline everything
    Stop putting on stories for refactoring, or taking a week off to fix that one file. It’s great that you do this, but it creates other big bangs. You should incorporate this in the way you work every day. Follow the scout rule; leave the code cleaner then you found it.
  4. Be transparent
    You need to be able to communicate with everybody what you are doing all the time. So don’t hide the stuff that you are doing, like making a file a little better while touching it. Refactoring and cleaning up should be part of everything you do so you should be open about it. However, keep in mind that you should not ask permission to do this! It’s part of your job, but be upfront about what you are doing. Also, don’t ask for forgiveness. Again, it’s not something you need permission for. You will make mistakes, you will clutter, you will overdo your refactors some of the time. It’s actually important that you make these mistakes, so you know what to watch out for, you’ll learn a lot from this process!

Is it all in the code base?

You can probably guess the answer, no it’s not. The most important part about software is not the people nor the code, it’s the system. What I mean with this is that the code base and the team go hand in hand. If the code base is a mess, the team is a mess as well. This would mean that for any problem you have when writing software, there are two ways you can approach it:

1) You can make changes to your team which will drive changes in your code base, or
2) you can make changes in your code base which will drive changes in your team.

For example, if your code contains three implementations of “User login”, you could consider this as tech debt, but it also represents an issue in communication within your team. Those different implementations should not have been there. So, can everything you read until now be changed by changing the team? Yes, it can! Just start by making everybody in the team aware of this principle and start communicating about this topic in reflection to your code base on a regular base and see what happens.

Another important aspect to look at is what software actually is. It moved on from building a product and being done a long time ago. Applications keep evolving, we use continuous deployment, the products are never done. Software development should be seen as an experience, involving developers, managers, product owners and clients, a group of creative effort. They’re more like a group of theatre people putting together a play, then a group of workers fabricating something physical. While a lot of developers don’t think they do creative work, the way we work in software nowadays actually makes a lot more sense in a creative model where people are collaborating then it does for a manufacturing model. The more we think about software as an interconnected part of code and people, the closer we’ll get to a code base we’re excited to work in. And you can do this too if you build trust among your team members and if you strengthen your connection, the code base will follow.

Architecture and big refactors

So now we know where we want our code to be, what the relation between our code base and the team is and how to get to the code base we want. One thing I haven’t mentioned yet is the solution a lot of developers yearn for, the big refactor. You see yourself struggling with the awful code day in and day out and you’re dreaming of a rewrite. If we only could build it again, we would build it a lot better. Write that jQuery project in Ember, rewrite that Monolith into micro-services. And sometimes it works for a little while, but if you don’t change the habits within the team, the clutter will sneak in again. You’ll just end up with a tangled network of micro-services just like you had a tangled network of class definitions in your monolith. Or you’ll go into the other extreme and over-engineer the whole project and create such a big mess of layers that nobody can’t find anything without a full search and rescue team with them. What actually is more effective is changing it little by little and let the people that live there do it. Teams should reach these insights for themselves, there should not be an outside architect role that tells them how to build things. Architects always seemed a great way to keep the structure clean, but as I said before, the team that lives in the code base is connected to it, the architect is not. It would be as if a stylist is coming to your house and telling you how everything should look. Don’t get me wrong, you should really ask help from someone that knows a lot about architecture should you ever need it, but it should never be the other way around.

Where did this all come from?

I didn’t think of the principle of livable code myself and I don’t want to take credit for it. It just made a lot of things fall into place for me and I really wanted to share it with the world, make people think about this. The first place I came in contact with the livable code was on a blog post from Uncle Bob, called Too Clean? I found it a really interesting read and love his conclusion;

“We should not be ashamed if our code looks a little bit lived in. On the other hand, we need to be diligent about cleaning up after ourselves; and not let the mess spin out of control.”

The article from Uncle Bob starts off with the mention of a talk by Sarah Mei, called Livable code, which was my real inspiration. A lot of the things you read above is my vision for software development after hearing her keynote. Should you have 45 minutes to spare, you should really watch it and hopefully, it will inspire you as much as it did me!

Did you love these tips and do you think it will get you to the livable code yourself? If you haven’t already, check out part one of this blog where John shares his experiences using the clean code principles and discusses the types of clean coders.

Related content

How to use data to build the workplace of the future