Search | Blog | Contact

Ledger For My Technical Debt 12

Posted by Ben Rady Wed, 27 Jun 2007 08:42:00 GMT

All projects accumulate technical debt. It’s just a question of how much and what you do about it. My personal method for tracking debt is very quick, easy, and useful…

Many wiser people than I have espoused that a comment is an apology for ugly code, which is something that I wholeheartedly agree with. So what better way to record your technical debt?

To do this, I take advantage of an oft-underused feature of most IDE’s, the “Task” or “ToDo” list. These tools scan through your source code looking for comments of a particular format, and then generate a list of items based on the comments contained therein. I have three basic comments that I use to record technical debt:

// FIXME
// FIXME With some explaination here
// HACK With some explanation here

The first comment represents short term debt. This is debt that intend to repay (by fixing it) before checking in. I usually use this when I’m in the middle of adding a new feature, and I see and/or create some debt.

The second comment represents long term debt. This is debt that I intent to repay the next time I change this module/class/method. I usually use this when I’m reading through code, without needing to change it, and I see something I think could be improved.

The third comment represents debt I don’t know how to repay. These are usually things like platform bug workarounds, which are sometimes ugly no matter how you write them…you just have to wait for the bug to get fixed.

With this system, I always know how much debt I have for a given project. When looking at the code, the description of the debt is right there, so I have all the information I need to take action without breaking flow. Finally, by keeping the debt record in the code, you reduce the chance that it will get lost or out of sync.

Comments

Leave a response

  1. Avatar
    YAChris about 2 hours later:

    Interesting how comments, intended to be one specific thing, have wound up with multiple uses: this reminds me of the (possibly apocryphal) story of the programmer’s shopping list in the IBM OS/360 source.

  2. Avatar
    zorkerman about 2 hours later:

    I find it to be very informative to do a fixme with a date:

    // FIXME 6/26/2007 This code is the devil

    Nothing like finding one of these that’s three or four years old.

  3. Avatar
    digitalsanctum about 3 hours later:

    I read once that a sign of a good hacker is one that does NOT introduce or leave hacks or temporary fixes in code and instead fixes them right away. I agree with the author (forgot where I read it) and I try to stick to the philosophy in my own work.

  4. Avatar
    Arnon Rotem-Gal-Oz about 8 hours later:

    Why not take this further and add // FIXME BY 6/28/2007

    And then add a task in the build script to fail the test if FIXME BY has elapsed This way you are less likely to find these debts accumulating dust :)

    Arnon

  5. Avatar
    Jason about 12 hours later:

    I’ve used this myself on my project, however I’m seen on the same large project if people don’t take accountability for monitoring these things the “todo” or “task” view in the IDE gets so filled with clutter that it becomes overwhelming. I like the idea of tieing it to the build system and have a build fail if something isn’t fixed in an appropriate amount of time.

  6. Avatar
    Ben Rady about 13 hours later:

    I’m not sure I agree with adding a due date to these comments. I want to fix these things as soon as I can. Putting a “due date” implies that either:

    a) I can ignore this debt until it’s due date

    b) Giving it a due date will magically add 4 hours to the workday so I’ll have time to fix it.

    I’m not writing these comments to motivate myself to fix the problems…I’m writing them so I’ll know what needs fixing if and when the opportunity presents itself.

  7. Avatar
    Gil Zilberfeld about 23 hours later:

    I’ve tried it myself, and it works – for personal use. I could not see that scale to all the team, which would then make possible Arnon’s suggestion. At the time, it was easier to keep the scope small (use as an actual to-do list) rather to explode with more features.

    And like all other things, it takes discipline, and and self-training.

  8. Avatar
    Jason 1 day later:

    I think you put the due date in because we’re human and get busy on other things and let it slide. The due date only works if you plug it into your CI, otherwise it’s just another field in the task view to ignore. Or if you’re really up for some excitement don’t put a due date and just have your build fail if there are any FIXME, TODO, HACK, etc. comments, period.

  9. Avatar
    Jukka Lindström 6 days later:

    I heard this nice practice from a colleague. Each day they automatically generated a graph from the count of FIXME, TASK and HACK markers (by module?), which clearly showed how the tecnical debt accumulated (and when it was repaid).

  10. Avatar
    Dean Wampler 8 days later:

    If you’re using Eclipse, MyLyn might be helpful. It offers task management and some annotations in source code, like comments with hyperlinks to the bug tracking system.

  11. Avatar
    Rickard Johansson 11 days later:

    Fulhack provides a nice way to mark your technical debt with annotations. This gives you the posibility to generate reports of all your hacks and fixmes.

    http://weakreference.blogspot.com/2007/06/fulhack-annotation-10.html

  12. Avatar
    Jeff L. 14 days later:

    A good rule to institute is that all “fixmes” are deleted by iteration end. Either they get fixed, as they should, or they don’t need to get fixed, or there’s something important going on that needs to be elevated, perhaps to an external task list.

    Most “TODOs” do not get “TODONE,” in my experience. It’s embarrassing to come across one of your own that’s a year or more old.

Comments