1 April 2013
By: Tomas Malmsten

Visualising technical debt

Technical Debt is something most teams struggle with in one way or other. One of the more common issues I encounter is how to visualise the actual cost of technical debt in a way that the business stakeholders understand. To achieve this I have used a special product backlog type with some additional data.

The debt needs to be tracked in two places. A comment of some kind is needed in the code which will identify and remind the developers that the debt have been logged and is being tracked. I have created a TODO like comment which I’ve called DEBT. The tag holds a link to the backlog item which is tracking the debt. When a developer encounters the comment in the code they need to read the item to understand what and how to deal with the debt.

The second place is the issue tracker for product backlog. The backlog item type needs to keep track of three things:

  • A description.
  • A time guestimate for how long it would take, in man days, to fix this debt. I usually refer to this as the debt.
  • Interest. The interest is calculated in man days spent to circumvent the debt.

When a new technical debt item is created two team members should take part. Two are generally better at both describing something clear and at guestimating how long it will take to pay the debt of. The new debt has to be described in such a way that when someone else encounter the debt in the code they understand how this debt is paid of and why it is a debt. Usually the code does a good job of this but not always. A guestimate is required. This defines how big the debt is and is central when evaluating if a debt should be prioritised to be fixed. In my experience guestimates are best made in man days, but if the team is used to doing guestimates in hours that’s OK to as long at the same unit is used when tracking the interest. Once the backlog item have been created a DEBT comment has to be added to the code. The comment should be placed where a developer would typically enter the indebted code. The comment should provide a link to the debt item so anyone can log interest against the debt.

When a team member works with the code and encounters the debt they read the debt item description and logs how much time they spend on coding around the debt. In other words how much longer does it take to complete the issue at hand then if the debt would not be present. This amount of time should be added to the interest field in the debt item.

Over time, and if the debt is sever this is usually only a matter of weeks, it will become evident that the team is spending more time paying interest on the loan then what they would spend to pay the debt of. Since both interest and debt is illustrated in the same unit this will become clear to non technical stakeholders just as well.

Further to making technical debt and its costs easy to understand for everyone it will also help to illustrate to the team when a debt should not be paid of. I have many times found my self thinking that a particularly messy part of the code really should be cleaned up and then realising that since it is so rarely touched it is really not worth fixing.

Tags: Legacy Code