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 grep.

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.