TODO: Add an intriguing title
January 5, 2022TODO comments are everywhere. And they're usually ignored. So just stop creating them.
Ya love ’em or ya hate ’em.
But why are they there?
I think there are broadly two categories of TODO comments:
- Something that needs to be investigated
- Something you know should be done differently, but you don’t want to take the time right now
- 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:
- Investigate or fix the thing right now. If it’s important, this is the best option.
- Simply don’t do the thing. If it’s not important, this is the best option.
- 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?
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.
How to handle schedule slippage on an agile project
If you have a fixed scope and a fixed timeline, you simply don't have an agile project.