TODO: Add an intriguing title

January 5, 2022

TODO comments.

Ya love ‘em or ya hate ‘em.

But why are they there?

I think there are broadly two categories of TODO comments:

  1. Something that needs to be investigated
  2. Something you know should be done differently, but you don’t want to take the time right now
  3. Ideas for future improvement

The TODO comment stands in as a little bookmark saying “Get back to me and make this decision or do this refactor some day!”

The trouble is… they almost never actually happen. Don’t believe me? Try this little trick on any code base with TODO comments, which will show you the last modified date of every TODO comment in your code base.

git grep -n TODO | while IFS=: read i j k; do git blame -L $j,$j $i | cat; done

If you actively use TODO comments, and you have zero TODOs, or the oldest is not more than a couple weeks old, I want to hear your secret!

So here’s my challenge to you:

Stop creating TODO comments!

Instead, do one of three things:

  1. Investigate or fix the thing right now. If it’s important, this is the best option.
  2. Simply don’t do the thing. If it’s not important, this is the best option.
  3. In the truly exceptional cases where something is important, but cannot be done immediately, track it in your issue tracker, not in a TODO comment. That is, after all, what an issue tracker is for, right?

Related Content

But we REALLY need TODO comments!

Enhance discoverability, and reduce comment rot by making sure every TODO comment references an issue number.

Why "Consider refactoring this" comments are silly

Code is always subject to refactoring when the need arises. Adding a comment to that effect is just noise.

Agile houses

We often contrast software to physical buildings--the idea that software is easy to change, whereas buildings are difficult to change. But is this really true?