«    »

Using To Do Comments in Code

I am a big proponent of using to do comments – comments prefixed by a specific identifier such as "TODO" – in a code base to indicate outstanding tasks or issues with the code. I have encountered developers who are either unfamiliar with the practice or who do not follow it as deliberately as I do, so I thought I would explain my method.

The idea of to do comments really only makes sense with the proper tooling. The Eclipse integrated development environment calls them task tags, and supports providing any number of custom identifiers that when found in a comment will cause Eclipse to add that comment into its Task view. The default identifiers that Eclipse ships with include "FIXME" and "TODO". You can then browse the task view, sorting or filtering the tasks by various criteria, to see the outstanding work. Continuous integration servers such as Hudson running the Task Scanner plugin can produce statistics, reports, and graphs of the outstanding tasks in a code base.

Why use to do comments?

When doing my own coding, I use to do comments when ideas come to me regarding code I need to write or special cases I need to handle that are separate from what I am coding right now (usually in order to get the current test to pass, via test-driven development). Writing the idea down gets it out of my mind and out of my way. Using a to do tag reassures me that it will not be forgotten: part of my definition of done is to ensure that there are no to do comments remaining in the code.

When looking at code written by other team members, I want to be able to quickly tell what state the code is in – is it completely finished, or is it a work-in-progress, with scenarios or requirements left to be handled? The reason I care is that if I think the code is supposed to be finished, and see issues or outstanding work, then I will raise the issue(s) with the developer. Fairly often when I have done this in the past, the developer reassures me that they were already aware of the issue and would resolve it. That is usually when I recommend the use of to do tags as a communications mechanism to the rest of the team as to the status of the code, especially if someone else had to take over working on that code. And as often as not, unrecorded issues that developers say they are aware of and will resolve later end up being forgotten and left unresolved.

I hope I have convinced you of the value of using to do comments. Please leave a comment and let me know what you think about the practice.

If you find this article helpful, please make a donation.

4 Comments on “Using To Do Comments in Code”

  1. Mike T says:

    I think the important thing to remember is the definition of done requiring that there are no TODOs left in the code. At Intuit the QuickBooks code was littered with many TODOs, HACKs, XXXs, etc. going back many years. And by many years I mean in some cases 10! Unless it’s someone’s job to remove them, they won’t get done again. Plus, they’re usually short and make assumptions of knowledge that are likely lost by the time the next person finds them. e.g. “Fix this after beta”. That’s a full quote, there was no other comment. It appeared in many places for different things, it wasn’t always clear what needed to be fixed, or how.

  2. Mike T says:

    (continuing) … Or even what beta they were talking about, though the comments were occasionally dated as far back as 10 years, some times more. Some pre-dated the current version control system (Perforce, a good product BTW) which had records back to about ’93 IIRC.

  3. Phil vonSaldern says:

    I have used FIXME or TODO according to the situation for well over a decade and it has served I and my colleagues well. It’s easy to search code for outstanding tasks or issues this way. Of course, inline comments must be explicit enough to stand alone because I probably won’t remember why they’re there without explanation and certainly no one else would. I am pleased to find that this is such a common practice.

  4. Tomek says:

    I used FIXME and TODOs for a long time and I think they are quite useful. The only problem is – what was already reported by others – if the comments are not meaningful enough. Right now our team policy is to clear all FIXMEs before a thing is “done”, but TODOs can stay provided that they are really well documented. We still discuss this, because there is a threat that TODOs will never be cleared. If we find it hard to get rid of them “later” (provably during a special TODO-hunting session), we will probably update our policy and decide to clear them before a task can be marked as “done”.

«    »