Keeping tech debt in check with Ruby on Rails and Harrow

This article is about all those `TODO` and `FIXME` comments you have in your code base, and how to get rid of them. The article assumes that you are working with Ruby on Rails, but the underlying problem is not specific to any single technology.

The Problem

Most likely you have already seen (or written!) comments like this in
a code base you have been working on:

class SomeController
    def some_action
        # TODO: move this to SomeModel
    end
end

Comments marked with TODO in the code serve as a constant reminder to your future self and your team mates that something needs to be done. Unfortunately the act of writing down what needs to be done often causes one to feel that something has just been done. Documenting problems is the first step to solve them, but not the last.

Let’s examine some of the possible reasons for why these comments are written in the first place, instead of just fixing the problem:

  • You are working on a feature and see that something is wrong with code nearby the feature you are working on. You add a FIXME note to that code, to remind you to come back and fix it when you have time, so that you can continue working on this feature without your mind being occupied with fixing that other problem as well.

    You forget about it and don’t take the time to fix it.

  • Your userbase has grown and you notice a slow controller action. The controller action is still fast enough, but further growth could make the controller action unusably slow. You add an OPTIMIZE note to the controller action to take care of the problem before it is too late.

    You forget about it and optimize when users start complaining.

  • You need to cut some corners in order to deliver on time. You feel bad about the quality of your work and add a TODO note, to improve the code later to match your usual standards of quality.

    You forget about it.

All of these occur often than we’d like to think and I certainly have been guilty myself of adding a comment and never doing anything about it. It is very easy to just leave comments like this in the code, thinking that the issues will be resolved in the future and the comment removed. In practice these comments tend to stay in the code base far longer than anticipated and the issues they describe are rarely addressed. These unaddressed issues are a form of tech debt and leaving comments about them before moving on is a way to rack up tech debt quickly.

How Rails solves the problem

Luckily the developers of Rails are familiar with this problem and Rails ships with a tool for addressing this issue: rake notes. This rake task search through your code base for comments tagged with FIXME, TODO or OPTIMIZE and outputs a list of these comments in your code base, including the file in which they occur.

Here’s an example of what you get when running bin/rake notes in a project:

$ bin/rake notes
app/controllers/users_controller.rb:
  * [3] [FIXME] don't list banned users

app/models/user.rb:
  * [3] [TODO] hash passwords correctly

This helps a lot with keeping an eye on outstanding issues that need to be addressed. If a team member finds him- or herself in need of something to do to cover a short slot between meetings, the output of bin/rake notes is a good place to start looking for small improvements.

Sometimes you might find yourself in need of referring to an issue in your bug tracker in the code, to document code that has been added to solve specific bugs, e.g.

class UsersController < ApplicationController
  def sign_up
    # JIRA ACME-1234: banned users should be blocked from sign-ups
    render :banned if Users.banned?(params[:username])
    # ...
  end
end

Luckily Rails has you covered here as well, it supports custom “annotations” (as Rails calls them) as well:

$ bin/rake notes:custom ANNOTATION=JIRA
app/controllers/users_controller.rb:
  * [7] ACME-1234: banned users should be blocked from sign-ups

One possible use for this type of annotation is to mark places that likely need to be changed when working on a specific ticket. This makes it easier for new team members to find the right place in the codebase when they start working on a ticket.

Why Rails’ solution doesn’t work

As nice as the solution provided by Rails looks, it has one major problem: somebody actually needs to remember to run bin/rake notes and do something about the output.

In itself that might not seem like a big deal, surely somebody in the team will run this command! Unfortunately somebody usually means nobody — or put another way, somebody often means somebody else.

On top of that, once your Rails application has grown and the bootup time for running rake is in the range of several seconds, few people have the patience to wait bin/rake notes to finish.

While a short list of TODO and FIXME notes is motivating (“I just have to fix that one issue to clear the list!”), a long list of TODO can be demoralizing (“There is much wrong with the code already”). Not maintaining this list by addressing or removing issues causes it to grow indefinitely.

How Harrow helps

Harrow can help you with solving these problems by automatically running rake notes for your team and informing them about the results. That way nobody forgets to run the command, because nobody has to run the command manually anymore.

When setting up a new project on Harrow, in the setup wizard please choose the “Ruby on Rails with Capistrano” defaults.

Harrow will create a tailor-made Rails set up with preconfigured tasks, including a task for running rake notesin your project:

Clicking the “Run” button clones the repository you have configured when creating your project on Harrow and runs rake notes in that repository.

There are multiple choices for automating this, you could have Harrow run the task:

  • every time a commit to master is pushed,
  • before your Sprint Planning meetings,
  • or after running your tests.

Successful runs of the task can be reported either to you and your team’s Slack channel or via email. All of these can be configured from the Project settings.

Once everything is set up, you don’t have to worry about these notes anymore. Harrow keeps and eye on them for you and you don’t miss it anymore when your tech debt is piling up without anyone noticing.

Stay tuned for more ways of using Harrow to handle repetitive chores for you!

Want to try Harrow.io? Start immediately with a 14 day free trial or learn more.

No credit card required – completely free for small or public projects.


Want to try Harrow.io? Start immediately with a 14 day free trial or learn more

Harrow.io is a platform for Continuous Integration, testing and deployment, built by the team behind Capistrano.
Add powerful automation and collaboration capabilities to your existing tools.

  • Automate any software, in any language.
  • Create self-documenting, repeatable web-based tasks
  • Make them available for your team-mates
  • Trigger tasks automatically based on Git changes and webhooks.
  • Get notified by email, slack, etc.
  • Free for small projects

Test, deploy and collaborate online easily, using tools you already know and love.
Works seamlessly for PHP, Node.js, Ansible, Python, Go, Capistrano and more!

Learn more Start your 14 day free trial

No credit card required – completely free for small or public projects.

Engineer with a passion for all things unusual, functional and fast. Dario wields tools from TCL to Prolog to get things done in ways that wouldn't occur to most people.

Start Using Harrow Today!

Harrow is flexible, powerful and can make your team much more efficient.

Start free trial