Keeping Track of Technical Debit

technical-debit.md

Keeping Track of Technical Debt

Don't forget your debt! Developers have a tendency to forget the bad or ugly code they write. In the Real World™, there are times when sacrifices in code quality need to be made in the interest of time. We call it "cowboy coding" and it's a slippery slope that can lead to loads of technical debt.

A big problem is that it's too easy for technical debt to be out of sight and out of mind. There are a few good ways to increase your debt's visibility.

Code Comments

Your first step should be to add code comments where appropriate to document technical debt as it arises. Fight the urge to deny the fact that you're writing less-than-awesome code. Try to include what's wrong with the code in question as well as at least one potential solution.

module ApplicationHelper
  # FIXME: Displaying flash messages this way prevents us from using
  # flash for anything else. Consider whitelisting flash keys that are
  # used specifically for messaging.
  # See: http://collectiveidea.com/blog/archives/2015/01/28/non-message-flash-in-rails/
  def flash_messages
    content_tag(:div, class: "flash") do
      flash.each do |key, message|
        concat content_tag(:div, message, class: key)
      end
    end
  end
end

Start your comment with the FIXME, TODO, or OPTIMIZE tag. Rails includes a handy rake notes task that lists the locations of all comments beginning with these tags.

DEBT.md

Technical debt can't always be pinned down to a single location in the code; sometimes it's systemic. Systemic debt is hard to track if there's nowhere to document it. A DEBT.md file provides that location.

The purpose of DEBT.md is to be the canonical source of where and how the application code can and should be improved. This should not be confused with how the application can be improved. DEBT.md is not the place for feature requests.

Put DEBT.md in the root of your application. Link to it from the top of your README. Send the link to your client. Do whatever you can to increase the visibility of this document. A long list of debt might be embarassing, and it should be! On the other hand, if your DEBT.md file is empty, it's time to re-read your code and uncover more debt.

Give each debt its own section. Explain the problem. Describe at least one potential solution. If applicable, give a deadline for when the issue should be resolved.

# Technical Debt

## Web/API Controller Action Duplication

Many actions in the application occur via both the web interface and the
API. Because those actions appear in separate controllers in separate
namespaces, much of the code is duplicated. The duplication produces the
danger of updating logic in one location but forgetting to in the other.

Consider moving to the interactor pattern, pulling the shared
functionality into an interactor and using the same interactor in both
controller actions.

See: [Interactor](https://github.com/collectiveidea/interactor)

Changes to DEBT.md should be subject to the same review process as your code. Other potential solutions may be proposed, and your entire team is made aware of the debt.

A Lannister Always Pays His Debts

Just as with financial debt, eliminating technical debt requires a plan and a schedule.

Plan periodic debt cleanup time and build this time into your estimates. The accumulation of some technical debt is inevitable but with discipline, it can be managed and minimized.

Do you have another strategy to deal with technical debt in your applications? What works (or doesn't work) for you?