Tag Archives: documentation

Thoughts on TODOs

I’ve seen many TODO code comments in my life so far, and they’re something I think should be handled with care. From discussion, and online reading, I realise that the best way of using them will vary between people and teams.

The biggest issues in my opinion are:

  • hidden work – there is no visibility in the bug/task tracker/project plan of work that may need to be done based on a TODO
  • accidentally checked in code with TODOs next to it
Examples:
@Ignore //TODO don't check in, fix this test

catch (SomeException e) {
    //TODO do something about this
}

//TODO this whole thing will need to be reimplemented before feature x can be done

A good-sounding method I’ve heard of being used is the following (although I haven’t used it myself):

  1. developers put their name or a bug ID next to TODOs
  2. before each release, remove all TODOs – delete them if no longer applicable, or create tasks for them.
    1. Item 1. helps with this
    2. Remember to include all file types (those that your IDE might not scan by default)
    3. Also applies to FIXMEs

This goes some way to address the issues and avoid TODO-explosion in a project, while not adding too much overhead to day to day development that might discourage developers from documenting issues, improvements and so on using TODOs.

Advertisements