But we REALLY need TODO comments!
January 7, 2022Enhance discoverability, and reduce comment rot by making sure every TODO comment references an issue number.
I recently suggested breaking the TODO comment habit. But if I’m honest, there have been times when I’ve still found TODO comments to be useful.
But even the most useful TODO comments tend to rot in most code bases. They’re also usually hard to find when you need them.
“I remember I left a comment about this bug in a couple places, but I can’t remember where now.”
There’s a fairly simple solution to this problem:
Every TODO comment should reference an issue number.
This is easy enough to do without any special tooling, other than self-discipline:
// TODO #123: Make this work with CORS
But even better, you can add a step to your CI pipeline that will fail any time a TODO comment is added that does not reference an issue. A simple grep can often be enough to do this.
This enhances discoverability immeasurably, as now all you need to do to find all relevant TODOs is a simple
The truly ambitious can go a step further, and provide full integration with their issue tracking. Imagine that your check ensures that the referenced issue is active, and adds a comment to the issue, and even prevents closing the issue without removing the TODO comments?
I’m not suggesting everyone should go to this extreme. For most teams, a little self discipline about only adding truly essential TODOs is enough, and a short grep in your CI is all you need to do sufficient enforcement, if you feel that adds value.
TODO: Add an intriguing title
TODO comments are everywhere. And they're usually ignored. So just stop creating them.
Many people don't understand refactoring, and this leads to several anti-patterns.
Can a "feature factory" be "Agile"?
You may achieve technical excellence, but without a holistic agile approach, you may just be shipping technically excellent, but worthless features.