Everyone loves to complain about technical debt, but not all technical debt is created equal and tackling it can become a nightmare if we can’t find a clear path to resolving it. Here’s a simple analogy that will help your teams think about how to approach their technical debt and to get it under control.
Imagine you have just thrown a big party at your home and now, the next day, it’s time to tidy up. You might be a bit tired (or even have a headache) but as you hate living in a messy environment, you decide to get started and to get it done as quickly as possible. The weekend is almost over and if you don’t manage to get this situation sorted out by Sunday night, you’ll likely not have time again until the following weekend.
Some of your guests were, to put it mildly, partying a bit too hard and have left your personal possessions and even your furniture randomly strewn around the rooms of your house. Some of it even spreads out onto into the garden and onto the street outside.
Joining a project which has existed for some time, or entering a new role at a company with “it has developed over time” IT systems can seem just as daunting as the aftermath of this party. There can be lots of stuff where it really shouldn’t be and you only have limited resources to dedicate to remediating the situation. The mess will ultimately incur a cost on your team and it may impact your ability to deliver new features in the future.
What should we do?
Fix your externally facing technical debt first
Firstly, we should consider the items lying in the road and in the garden. The garden gnomes standing in the middle of the street could cause an accident. We should rescue the little fellas before something terrible happens. The messy situation outside the house will also give a very bad impression to our neighbours, which may cause them to complain. A repeat offender may even be reported to the local government, and in extreme cases this could result in an eviction.
Having a tidy front of house means that the mess inside has no impact on the neighbourhood. Indeed, you could even gut the building interior entirely and rebuild it without the neighbours noticing.
It is a bad situation to have a project’s technical debt impact neighbouring code bases. If we have messy, or low quality APIs or events, missing or confusing documentation, we can create additional work for and cause poor design to leak into other teams codebases (or even cause cause bugs). This situation will also cause frustration in neighbouring teams and, in extreme cases, could result in management intervention. Ensuring that the technical debt remains localised within your system boundary means it remains contained and it does not spread.
Having clean interfaces (and documentation) means that the mess inside the system has no impact on neighbouring systems. You could even replace the entire internal implementation without impacting dependent systems.
Ok, now we have the outside of the house safe and tidy, let’s go back inside. Oh dear, it’s bad…. really bad! Where to start?
Getting stuff into the right rooms
A good strategy for tidying up is to simply move all items and mess into the correct rooms. This means moving the furniture, large items, small items and just dumping it into the correct space approximately. Don’t spend time tidying up at this stage, were only interested in getting things generally in the right place.
This means the toilet seat is back in the bathroom, the sofa is back in the lounge, the knives and forks are back in the kitchen.
Don’t waste time organising the cutlery in the kitchen drawers, get the high level separation into rooms done first. Tidying up more than this will be done later (and will be more efficient as a result of this first step).
You’ve now separated the mess into distinct rooms, which makes each room a separate (and much smaller) problem to solve. People can also tidy up in parallel more easily too.
From a software perspective, ensuring the high level separation of concerns into modules and packages is a key way to keep the code base organised and understandable. Even if the code is still a mess, having code where you would expect to find it makes your future work easier and goes a long way to improving maintainability.
Getting the high level structure right makes all our future work easier. Don’t waste time making your code beautiful, just dump it into the correct location (as is) and we’ll revisit it later.
Having code structurally separated into modules or packages can also make it easier to work on technical debt in parallel.
Now that job is done, let’s start to make things beautiful…..
Focus on where you are most active
The party took place in every single room in your home, but there are probably some clear priorities you can make to ensure life in your home gets back to normal as soon as possible. You’ve already separated the mess into distinct rooms, which makes each room a separate problem to solve. Which rooms should we focus on first?
The criteria for this is where are you most active in your home? Rooms like the kitchen or the bathroom are vital for being able to live in a home. If you can’t prepare food or use the toilet, or get washed, you aren’t going to get very far. The bedroom and the lounge are perhaps secondary, as you could perhaps sleep on the sofa until you sort out the bedroom. It won’t be as comfortable, but you’ll survive. Places like the cellar or the attic are last as you seldom use those rooms.
Now is the time, for example, to organise the cutlery in the kitchen drawers to make your kitchen space usable and efficient. All of the cutlery is at hand in the kitchen already thanks to the previous step, so arranging things is easier and doesn’t involve searching the house for that last tea spoon.
In software, technical debt incurs a cost when we want to modify code. This cost is therefore most acute in areas which are under very active development. Having technical debt in code which hasn’t been changed in months or years is not a good place to start. Instead, focus on that service which is continuously being updated with new features for your customers.
For this reason, the biggest return on investment is going to be your most actively developed areas of code. This might include API methods which are constantly evolving, or your domain model which supports all your use cases.
Don’t tidy up everything
Your house is now is a usable state. The most important rooms have now been done and things are looking much better. Now is the time to remember that a full house clean up will have diminishing returns. Continuing to tidy up is tiring and time consuming, and now you’re getting less bang-for-the-buck for the effort you’re investing. We need to be pragmatic!
Places like the cellar or the attic can perhaps be completely left alone as you don’t often use those rooms anyway. Let’s face it, they weren’t in an amazing state even before the party!
The bedroom might be a candidate to do later, but to tidy up a little bit incrementally every night before you go to bed each time you re-visit the room.
In software, it is often also not a good investment to tidy up absolutely everything. Indeed, a low level of background technical debt is probably a normal situation for a productive development team. That batch job that has been running for 5 years can be left alone, as can those infrequently used REST endpoints.
Software engineers are like artists and can often strive for perfection for perfection’s sake. Being pragmatic and knowing when, and when not, to live with technical debt, is a great hallmark of a senior engineer.
Perhaps we can also schedule some of the technical debt tidy-up in the future incrementally every time we revisit those REST endpoints with new requirements.
Conclusion
Technical debt can be overwhelming, especially when combined with time pressure and limited resources. Using a careful mix of prioritisation and pragmatism you can make meaningful progress to getting your technical debt under control.
Isolating technical debt within system or module boundaries can reduce its impact and may even be considered a full mitigation in many cases.
Don’t try to eliminate all your technical debt just for the sake of it. Think about diminishing returns and invest your resources where it has the biggest impact.
Contact me if you want to talk more about technical debt.