Everyone is aware that code with comments is a bad thing. It will inevitably decay, and future developers will be wondering if there is any need for it at all.
Every developer is aware of this. So they often remind themselves to follow up the commented out code with a TODO comment, to see that something needs to be done. Many IDEs support this idea and can show you all TODO comments in your current project.
However, I think using TODO comments to remind yourself of work that needs to be done is a very bad idea. Here is why.
Have you ever seen anything like this before?
uint8_t result = calc_costs(num_people, month); // TODO
My guess is that you have. And what does that TODO comment tell you? The answer is: Not much.
Someone obviously wanted to change this line at some point. But why? What did they want to change? And by when?
If you are lucky, you can use git blame or some other source control magic to find out who added the TODO comment.
But even that might not be much help. You may have found the culprit, but does he or she remember what the TODO comment was for in the first place? Maybe it was even you who wrote that nasty comment, but you forgot about it long ago.
So what does that comment do for you? Absolutely nothing! Do not let this happen. Once you start putting TODOs like this into your code base, they will start to grow. And the more TODOs you have, the less you will be tempted to clean them up. It is just like in your own home: A single plate is easy to clean right away. But if you let the dirty dish pile up, you may procrastinate so long that it gets bigger and more encrusted, and you have already forgotten that your favorite mug is among all the pots and plates. Don’t let that happen to you!
Now, you may be thinking that it gets better if you add a more descriptive TODO comment
uint8_t result = calc_costs(num_people, month); // TODO Stefan Fill optional parameter price_per_item
OK, now you know who wants to change something (Stefan) and you know what he wanted to change here. But will he remember? When will he do it? Will it improve the situation?
Of course you can go and ask him. But maybe he is busy, on vacation or not in the project anymore. Who will take care of this TODO?
And if there are multiple TODOs in the code you are working with, are you going to ask every single person? Imagine how long that would take.
So such a comment is not really helpful, even if you think it is a great reminder when you write it.
But there are some things in your code that you cannot fix right away, that need to be left in a suboptimal state and revisited later. How do you let yourself and your fellow developers know?
The solution is simple: Link all your TODOs to the place where you keep the rest of the work to be done: Your issue system. Only if you have a ticket for a TODO will you get it done. And if you can’t do it, someone else can.
Write a ticket for every single TODO. And in the ticket, include all the details about why the TODO was necessary, and what should eventually be done about it.
uint8_t result = calc_costs(num_people, month); // TODO in ticket COOL_PROJECT_123: Fill optional price_per_item parameter when we get it from purchasing
This way, the TODO will always be in your face, because you will always have the ticket in your backlog, and you will eventually schedule it. Or you will see why the TODO cannot be solved yet, because it is blocked by another task.
And when someone else comes across the TODO comment, he or she will see the ticket, can always see who put the TODO there and why, and can rest easy knowing that someone will actually do it. No more wondering, no more head scratching.
So make that your new mantra: Every TODO has a ticket!