2 new positions now open  🙌
Yesterday, I tried to explain the concept of technical debt. Today, I’ll try to suggest a practical way to track and deal with debt in your project. As w...

My number one piece of advice with technical debt is to keep a register in a simple format in your source control repository along with the source code. A Markdown document is a simple and easily understandable way to do this.

Make sure that every developer on the team knows about and understands the register. Each time you add to the debt, add a corresponding entry to your register in the same commit as the offending code.

Sometimes you only realise that you’ve taken on debt after the fact, maybe because a library you are using is not as capable as you thought, or because requirements change unexpectedly (here at Made by Many we call this a ‘change bomb’). That’s OK, these things happen on software projects. The important thing is to get a handle on the size of the debt as soon as you can and make sure you enter it in the register.

When you pay down the debt again, remove the corresponding entry from the register and commit that back to your repository.

Make it a routine to conduct regular sweeps of the debt register, and make sure you have an active plan to address each item. Once per iteration is probably a reasonable frequency to do this sweep.

Share the register with your client, and make sure they understand the reason for incurring the debt, and the size of the likely repayment. This means that you need to help them understand the motivation for the sub-optimal implementation, the side-effects that it is likely to produce, as well as the anticipated cost of perfecting the implementation such that the debt is paid off.

You owe it to your client to help them understand the impact of your collective decision making on a project. Not enough people understand that all systems are a collection of trade-offs, and technical debt is one of the expressions of such decision-making. This can often be an awkward conversation if the concept of technical debt is new to your client, but your honesty will pay off in the long run.

The most important thing for clients to understand is that they need to have a budget for continuing development of their project. Too many projects make it to release and are then allowed to rot, and in many cases the client will not have been made aware of the consequences of such an approach, so they may expect you to be able to just pick up where you left off, no matter how much time has passed. Helping them to understand how software development works is part of your job if you’re a technologist.

If you’re dealing with Grade 2 debt, where your developers are telling you that you need to rewrite your system, the best thing you can do to defuse the inherent emotions is to get them to create a debt register for you. Each entry in the register should be clearly understandable by developers and non-technical people alike, and they should all be actionable.

Ask them to estimate the effort involved in resolving each item in the register in a planning game, and compare this cost to the cost of rebuilding from scratch. Don’t forget that if you let them rebuild the system, they will be building a system that also includes new debt – since there’s no such thing as the debt-free system – so factor in the cost of paying that off too.

You’ll almost certainly find that it’s more cost efficient to modify the existing system than it is to rebuild it.

Judiciously incurred and well-managed technical debt can form part of a sensible approach to software development. Just don’t forget to have a plan to pay it back before the heavies with the baseball bats arrive and take a special interest in your knees.

James Higgs

James Higgs

James has been developing software commercially for almost 20 years, in fields as diverse as manufacturing, TV broadcasting and retail. For the last decade and a half, he has focused almost exclusively on the web. Today he is increasingly fascinated with mobile devices, in particular Apple's iOS devices.