[Fakira]

TODO, as the name implies, should be things that must be done. Anything aspirational could be left as a mere ordinary comment.

Personally I hate TODOs and only see them as temporary things to act as placeholders for the correct code. At some point, I will go through all todos and clear them.

[kanox]

> TODO, as the name implies, should be things that must be done.

A lot of people use them for things that "could" be done.

[nosianu]

Also, there are things that "must be done" only if the code is extended but it may be perfectly fine as it is at the current state. So I add a TODO when I see that there will probably be the need for refactoring in the intermediate future, but there is no need in the current code base. That is a TODO that is triggered (to become a "true TODO") when that code is touched again, but it remains (justifiably) inactive for now.

The reason I use not just a comment is what others here already said, it gets highlighted by the IDE, and I have too many other "gray" comments that would not get read unless someone is looking at those sections specifically, so another regular comment would be easily overlooked. The suggestion for external tools or files is even worse: Pretty much nobody will check them when it's time for refactoring. It has to be inline. Sure, it can't become too much, but one such "triggerable TODO" comment for just a few modules is fine.

When I write the code I can often already see options to make it more scalable or generalizable, but as it is currently being use the additional cost is not worth it, and if there never is future expansion the code actually is fine as it is. When I already know what needs to be done because my brain is fully 'inside' this code it would be a waste to throw that knowledge away, and regain all the contextual knowledge and ideas with a lot of work a year later. Those are the cases when I add such comments. They are not necessarily "TODO" level at that point, I use that tag only when additional conditions are met and I'm sure I want to avoid missing the comment.

Occasionally, when I have some time over, I scan through my TODOs, there are about 2/1000 LoC. Most of them I leave alone because the condition for their realization has not been met yet, but sometimes I find one of them is worth doing at that point. If it was a general comment I would have no chance to find them that easily. If they were in an external tool or file they would deviate from the actual code more and more, since we do quite a bit of refactoring due to growth and changing needs. But if there's a highlighted TODO in a module you are refactoring it's impossible to miss, so it is easy to update or remove those if they become invalid, even more so than regular "gray" comments.

[cmyr]

yep, TODO is for things like possible optimizations or improvements that are known, and FIXME is for things that are... functioning, but incorrect by some reasonable definition. (YMMV)