TODO Comments Don’t Work

I recently came across a Harvard Business Review (HBR) article by Daniel Markovitz called To-Do Lists Don’t Work and found it very insightful. I use to-do lists all the time, but I’ve never felt like they help as much as I expect them to—that is, until I started following the suggestion that Daniel mentions in this article.

Much like the practice of making to-do lists, I tend to leave TODO comments while I am writing code, noting areas that should be cleaned up or need improvement. Yet, after reading this article, I started to notice some patterns. I tended to complete the “easy” items first, there was no prioritization mechanism, and ultimately, some of them would get left behind and forgotten.

In Daniel’s article, he suggests “living in your calendar” instead of creating a standard to-do list. By living in your calendar, you deliberately schedule to-do items and allocate a specific amount of time to accomplish them.

So I asked myself, how could I apply Daniel’s suggestion to TODO comments?

TODO Comments Are Just Comments

TODO comments can be very helpful when you want to highlight areas of a codebase that need improvement but don’t have time to do so. Some IDEs offer features that find the TODO comments in your project to create a list for you (sound familiar?).

The biggest issue with TODO comments is just that: They’re only comments. Comments, without a large amount of maintenance overhead, tend to become stale and misleading. There’s no amount of static analysis that will keep comments up-to-date with the current state of a codebase. TODO comments are no different.

What’s the Solution?

Am I saying that you shouldn’t write TODO comments? Absolutely not! I write them all the time, especially while I’m in the middle of developing a new feature.

What I suggest is that you use another tool that is better at tracking these sorts of things: a backlog.

What better to-do list tool is there in the software development profession? A backlog is a detailed, prioritized to-do list that software teams use to complete features for a project. Stories in a backlog tend to stay more up-to-date than comments in a code base, which reduces the possibility of them becoming stale or misleading.

If TODO comments indicate missing functionality or code base improvements that should be completed at a later date, they can be converted into a new story in the backlog. Whether it’s a complex refactor or additional test coverage, each action item can be added to the backlog and prioritized by the team.

So next time you’re submitting/reviewing a pull request and notice a TODO comment, don’t leave it in your code base. Add it as a story in your backlog instead.

  • Matt Behrens says:

    It’s good that you mentioned that they’re useful inside of developing a feature. I try to use them, too, when stopping to fix/improve something is going to break my productive flow, but I want to make sure I come back to it before the feature ships.

    Not allowing TODOs to make it into a feature’s merge as a matter of policy is a really good way to make sure we don’t accumulate TODO cruft, I’ve found. Converting them into backlog items is an excellent way to deal with those that are too big or inappropriate to address inside our current work.

  • Jesse Piascik says:

    I feel the same way about TODO comments and use them all the time. I use, a tool I created to get them into the backlog. I’d love to hear what you think.

    • Alex Zurek Alex Zurek says:

      That looks awesome, Jesse! I’ll have to try it out on a side project in the near future.

  • Comments are closed.