Documenting and planning for technical debt


I've been working for the same software company for nearly 14 years now. Over that time I've seen plenty of technical debt being accrued. I think that is inevitable for any long lived software company.

However, we've never had a strategy for dealing with it. We are aware of the technical debt, people complain about the technical debt, but we rarely build any method of dealing with it into our plans. I know this is part of the reason why people have left our company.

I've done a search, but couldn't find any proven methods for dealing with technical debt?

What I've been doing personally is adding a file called to my repos with a description of what I think needs changing and why, along with an estimate of time.

The above is my primary question but I expect to have arguments about this, particularly from those who will assert "there should never be any technical debt". So anything you can provide which also makes the case for having an approach to technical debt would be appreciated.

Best Answer

I suspect your question will be closed for being too broad which is a shame as any developer who has been round the track a few times will have encountered this a lot.

But just to share my experiences - there are a number of aspects to this:

Unit tests

Paying down debt will no doubt involve refactoring legacy code. This is all very well, but you will soon become the focus of unwelcome attention if you start breaking things. A good unit test suite should be in place anyway, but if it isn't, get started on it, as these can give you an early warning that your refactorings are going awry.

Approaching legacy code

This is a topic that people literally write books about - the most famous of which can be found summarised here.

The nature of the debt

Not all debt is the same - how your tackle it depends on the nature of the debt. If it is simply an obsolete technology then it could simply be replaced rather than refactored. Hard to give much more advice without knowing specifics...

Getting buy-in

I've worked in places where management are all about features and bugs and simply won't entertain any time being devoted to "polishing". This of course is very short sighted. If you don't get buy-in to fix the problems, you're simply going to have to attend any problems while you're in the code doing other things.

Understand also, that it isn't just management buy-in, you need the buy-in of your peers too. They will have different ideas about how the various problems should be solved. Involve everyone and you'll find the whole process is a lot easier.

What are your rituals?

Some say you should never have technical debt. This is a pretty naive stance if I may say so. Perhaps what they mean is that your debt should be as low as feasibly possible (like household debt).

That being said, how much debt you have is a function of how you view it collectively. If it is always at the front of your mind to pay down debt wherever you find it, you'll find it coming down quite steeply. If you're looking to fix it in your free time (whenever that is), it is a long hard road - not least as you could simply accrue more debt in the time it took to pay another debt.

As for tracking it in the first place, it should be recorded it your usual work tracking tool. How you separate this out from the rest of the work will vary from tool to tool.

Related Topic