What do you do if you find a problem in your code base but can’t fix it right now? If you are like many developers you probably put something like a todo comment next to it, so you don’t forget it. Something like:
// TODO: We really need to move all this stuff into a seperate class it really has no bussiness here.
The great thing about this kind of comments is: The IDE can pick them up and display them in some kind of list.
But the problem is (at least in my experience): It doesn’t work. Lots of those comments hang around for months and even years, often until the code around the comments changed so much nobody knows what the comment is supposed to mean. I have even seen TODO comments copied around with the code they are embedded in (which of course is a symptom of another problem).
You might know the book “Getting Things Done” (GTD). If not, read it. It’s good stuff. One of the key points of the book is: Your inbox isn’t your to-do list. Meaning you don’t use your inbox (where stuff you have to do arives) as the list of things you actually have to do.
In your inbox you have no way to properly control, what is important and what is urgent. Nor do you know if the task is something that takes two minutes or two weeks, or if it has a specific due date on which it has to be finished. Therefor the recommendation of GTD is: Get you inbox to zero by reviewing everything in it and either doing it right now if it is quick or transforming it in a proper task and filing it to one of various lists where you can pull it from when you have time to do stuff that takes longer than two minutes. Those lists cary with them all the information to decide quickly what task you should tackle next.
The same thing applies to TODO comments in your code. Code is great for many things. Managing tasks isn’t one of it. But you probably already have some kind of issue tracker in your project. If you find something that needs fixing in your code: put it there. There you can discuss it, compare it to alle the other tasks at hand in order to decide what is most important.
As every rule it comes with some exceptions: Short lived TODOs are fine in your code. Like when you implement a new feature and suddenly realize two more tests that you need to implement. Go ahead put a TODO in your code. Just make sure you’ll remove it and replace it with actual code before your next push to the central branch.
For everything else: don’t misuse your code as a to do list.