Getting out of Technical Debt

Jacob Orshalick

Do you have a technical debt problem? Just like having too much personal debt can lead to financial ruin, technical debt can ruin a project. In my last post, I discussed the criteria I would like to see out of a solution to tracking technical debt. Now we’ll have a look at some common solutions to the problem with their drawbacks as well as the recommended solution.

Tracking technical debt in TODOs

This type of tracking involves placing a TODO in a comment above the offending code:

// TODO this is a major hack only for the short-term, need to fix this
public void hackyMethod() {
  // ... ...
}

This is a somewhat effective solution, as it consolidates the tracking in the code base, keeps the tracking close to the code, and points out broken windows. But, it creates issues with visibility. When planning time comes for a new iteration, the developers begin the discussion as new features come up. “Feature XYZ huh? I remember looking at the code there, and there’s no way with the complexity there we are going to handle that. We’ll have to refactor quite a bit first, then we can start on that feature.”

Unfortunately from the perspective of the business owner, it’s like going in for routine maintenance and finding out the last person who fixed your car just duct taped the leak in your air conditioner. You’re not going to be happy. If you know up front that there is still an issue that needs to be addressed, you feel much less inclined to throw a tantrum.

In addition, TODOs don’t provide any metrics about the problem. How do I know the complexity of the issue? Is it really that important to address?

Tracking technical debt on a board

This involves dedicating a board with stickies or cards attached that represent technical debt. You will often see axis on the board representing complexity versus value. This solution is generally more effective than TODOs as it provides visibility to the issues as well as metrics. It also allows developers to explain why there is benefit to solving the issue.

The main problem with this solution is its separation from the code. This approach, by itself, doesn’t point out broken windows in the code and it doesn’t identify the exact location of the issues in the code base. You can combine this approach with TODOs, but we then have a consolidation problem and the two tend to get out of sync.

So what’s the alternative?

The Task Scanner Plugin for Jenkins provides the best traits of both of these solutions. This plugin allows you to scan for open tasks in the code base and generate a report that is visible to the entire team after each build.

For example, we could define the following task tags for use in the code base:

  • TECHDEBT_1 – high priority technical debt
  • TECHDEBT_2 – normal priority technical debt
  • TECHDEBT_3 – low priority technical debt

The priorities should first be assigned by the development team and can be revised after discussion with the product owner. These task tags are then defined in the code similar to TODOs. The description should place an emphasis on describing the problem and the reason it should be addressed:

// TECHDEBT_2 this method contains a temporary hack to support HR 
// requirements going into effect on 7/15/2012.  This will affect our 
// ability to make changes to the employee retrieval service in the 
// future.  Story points:  2
public void retrieveEmployee(Long employeeId) {
  // ... ...
}

The Task Scanner Plugin scans the code base for these tags on every build. It then generates a nice report as well as statistics regarding the task tags you have configured. The statistics gathered include:

  • the number of technical debt instances
  • the priority of each technical debt instance
  • the description of the technical debt
  • highlighted code related to the technical debt
  • graphs describing the trends of technical debt
  • and more…

This makes the technical debt visible to the entire team after each build. The build can even be set to become unstable or fail depending on the number of task tags found.

This approach addresses the criteria for dealing with technical debt, but requires discipline among the development team. It relies on appropriate tagging of technical debt as well as quality descriptions of the problem. So let’s evaluate this solution in terms of the criteria we have defined:

  • Consolidate the Debt – technical debt tracking is consolidated in the code base
  • Eliminate Broken Windows – by notating the technical debt clearly in the code base, it’s obvious where the broken windows are
  • Make it obvious to everyone – the report generated by the build is available to the entire team and nothing is more noticeable than a build failure
  • Tell me why there is benefit – the report also contains the comment provided by the developer which provides the reasoning
  • Keep it close to the code – as with TODOs, we have the information about the technical debt directly in the code base
  • Track metrics about the problem – the priority system of the task tags gives a priority for backlog handling. In addition, charts are generated over time showing how much technical debt exists versus what has been addressed

If you have any additional suggestions for the solution or additional solutions you’ve tried that meet the criteria, please leave them in the comments.