The state of your codebase

It’s likely you’ve experienced a bad codebase, code that more resembles a jungle or code that is tagged “legacy” and is slowly but surely abandoned. What’s the impact of readability? Where should I strive to be? Depending on how well your codebase is suited to be read by humans, you can categorise them in one of 3 categories:

• Utopia: You read the code, so you understand the business
• Realism: The code is clear when you know the business
• Slow Death: The code requires explaining in addition to the business explanation

Utopia: You read the code, so you understand the business

This is the epitome of readability: The story the code tells is so clear that without prior knowledge you can have a look at it and understand both the code and the business domain. They are one!

Any new people arriving in your team will have an easy time understanding the code and picking up new tasks. Because no additional knowledge is required to operate this code base, it is painless when people are leaving, or projects are moved to a different team.

Whenever a new change comes, it will be clear which implications it has, it can even be a good reference for your business stakeholders who might want to know what the current business process is if they have new people coming or leaving.

No “wtf”-moments occur unless the actual business process is perplexing.

It’s called the utopian state for a reason, most business processes are too complex to be made into code that doesn’t require a business explanation to make sense.

TL;DR: The semantics in your code are so clear you can just learn the business domain from it

Realism: The code is clear when you know the business

This state is very similar to the utopian state: The act of changing the code relies only on your understanding of the business domain, however the code will not be able to teach you this knowledge, it requires someone else!

You need somebody that is adept at teaching you the business domain knowledge, this can be your PM, one of the developers or your actual users. It does mean however that any gap or mistake in the process of learning the business knowledge will cause a few “wtf”s because the code will tell you differently.

It also comes with a potential risk when someone leaves the team because it increases the possibility of these gaps or inaccuracies in passing on the business knowledge. This risk is relatively low though.

TL;DR: The semantics in your code are very clear so you don’t need to analyse how the code works if you know the business domain

Slow Death: The code requires explaining in addition to the business explanation

Here’s where it gets tricky… To change the code you need to understand the business, then you need to understand how the code works, AND how they relate to each other.

This extra required information causes issues in multiple ways:

First: it makes it much harder to process everything to make changes because you need to master these 3 elements before you can even add a 4th thing called “the new feature”. There is also a risk of making the problem worse because of this complexity.

Second: The reasons why this not-so-clear code was written is usually hard to remember: historic requirements, old workarounds, etc. It’s not an immediate problem when someone in the team was around when these things were written, but the transfer of this knowledge to the next generation of developers working on the project is extremely hard or impossible. If you’ve ever rewritten a project, this is probably the reason why! There was not enough knowledge available to make maintaining and updating the old project viable.

That’s why it’s called the “slow death” state. It will survive only for a limited amount of time which usually ends when a key person leaves. This key person is called upon when something in the code is unclear and requires some explaining. Losing that information and capacity is a huge hit and is hard to recover from. This is the state with a high amount of “wtf”s.

An important thing to mention is that this state is a very natural state to roll into. It’s very challenging to take a step back from the codebase you’ve been working on for a long time and that you’ve written yourself and see if this would be easy to read and understand by other people. Feature pressure tends to drive shortcuts and quick code for a quicker time to market. Although the short term gains rarely warrant the mess it leaves behind. [1]

TL;DR: The semantics in your code are not clear you also need to analyse how the code works on top of knowing the business domain