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 s/he needs 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 s/he understands 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 s/he reads the debt item description and logs how much time s/he spends 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.

  • Why not just improve a little of the bad code every time you see it instead of documenting the bad?

  • My personal thought is that "technical debt" items are those things that are too big to pay off in small amounts.

  • That is my though as well. If a debt is small enough to hide with a reasonable estimate for another task then that is preferable. But in most code bases I have worked there have been debts that are to large to do so.

  • David Allen wrote about "Why bright people procrastinate the most" in his book Getting Things Done. I experienced this: a sense of dread when I realised all the unfinished stuff in my backlog. I won't say that it *depressed* me, but I felt all kinds of guilt-related emotions when I saw how much stuff there was "to do".

    Good news: part of the exercise involves recognising that you don't have to do it all. As long as you get that, the act of writing the whole backlog down won't hurt quite as much. I like to warn people about this effect when recommending similar exercises, such as the one that your article describes.

  • When I see "technical debt", I read "legacy code". If you have tests set to a piece of code, you can clean it with no fear, so the debt (if existent) will be very small and the code can be improved easily and quickly like @twitter-14979481:disqus suggested. But if you have legacy code, it will always be a challenge to change it, and further work to understand it and set tests to it will almost certainly be necessary, i.e. you have debt for not having done that (tests and clean code) in the first place.

  • That is a very good point and one I didn't even think about. I always take for granted that the product backlog is a which list and as such not everything will be done. But this is of cause not everyones idea of a backlog.

  • This is one of the reasons that I encourage people to drop the bottom 80% of their backlog from time to time. Apart from the clear waste of effort (the reason Mary Poppendieck so roundly suggests it), it makes many people feel negative emotions like guilt and hopelessness.