Todo Comments Considered Useful

Only positive arguments here. See TodoComments for a basic explanation of what TodoComments are. See TodoCommentsConsideredHarmful for counterarguments and TodoCommentsDiscussion for an up to the minute discussion.

TODO comments in code are a useful tool - one might even say the simplest thing that could possibly work.

"Going through all those comments" is rarely necessary, and when it is done it's not much effort. Tools can help to organize the TODOs if you do like trawling through them. If you can stand a little more complexity, consider adding a note in square brackets after the word TODO to classify your TODOs by type and/or severity.

The cons aren't cons:

Software development is endless work. TODO notes don't create extra work. They can reduce work by recording good ideas when you have them, rather than making you think of the same thing repeatedly.
TODO notes don't make you violate OnceAndOnlyOnce: there's no reason to duplicate what's written in the TODO note.
Organizing it is helped by tools, many of which will be in use anyway. If the information isn't there, you can't organize it.

Not everything about software can be tested by a UnitTest. Clean code doesn't show up as an extra green tick in a unit test. Even XP understands that there are certain background tasks that are necessary in order to allow the primary work of delivering value to the customer to happen. Not everything is a direct result of a user story. Some things are the indirect result of user stories. TODO notes are one example of good programming practice that is needed to support an efficient development style.

Writing a test that fails for something you haven't implemented yet would seem counter productive as your tests will always fail. TODO is very simple. It means what it says. It contains details you don't want to handle now, but need to, but will get to later. If you don't have the discipline to handle todos in your code than that's your issue. Don't confuse your weaknesses with mine.

It depends on how you use them. I use them when I realize that I could improve the code but I don't want to get sidetracked from my current task. Once my current unit test passes, I go through and address the TODO comments before checking in. These aren't bugs, so they don't belong in a bug database. They don't require that I write a new unit test while I'm focused on passing another unit test. They aren't related to user stories. They are usually opportunities for refactoring. TODO comments are a time saver when used judiciously. -- EricHodges

TodoComments are one of the best habits I ever formed. They always work. I don't always have access to a bug database; it depends on the environment (e.g. beginning of a project, or brain-dead management restricts access to entering bugs). Also, integration of bug trackers into normal workflow is 100% lousy, IMHO. Some TODOs translate into low priority bugs, which can basically get lost in the system. The TODO is always right there, staring at you, every time you look at the code. Honestly, I really don't see any good argument against them. -- DougMerritt

Part of the problem may be tool support. I use Eclipse. It generates TODO comments when it creates classes/methods for me. It lists all of the TODO comments in the current project (right after errors and warnings) so I don't lose track of them. Perhaps the anti-TODO folks don't have that kind of tool support. -- EH

But they are so convenient. I can be modifying one method for one purpose, see that it needs some modification, drop a quick "//TODO -" in it and continue with my work. After I'm done I look at the bottom of the screen and see it suggesting something else to do. I also keep an external task list of requests and ideas, but I have to change context to edit that. I can spit out TODOs without changing windows. Eclipse provides the overall view. If you're writing any Java code I highly recommend Eclipse. -- EH

TODO should be considered extremely helpful, especially in combination with Eclipse. First of all, it is elementary that there are decision you may want to review, refactor, find better ways, etc. You can't get everything perfect from the beginning. Some things are important and need to be addressed as soon as identified, some problems or just issues can be addressed later, maybe in relation to other design/coding decisions, so that you can optimize your workload. On the other hand, as soon as you identify an issue, better mark it as such (it need not necessarily be a bug), so that you don't loose that knowledge. Our brains do not have terrabytes of storage attached.

I've used TODO just this day, when I helped a colleague out of stumble point, but I needed a proof of concept that the alternative worked. Because it is his job, my interest was only to validate the proof of concept, with little consideration for the quality of implementation. I left him a TODO comment explaining how the proof of concept code should be refactored towards solid code. Like every other good thing TODO has potential for abuse, but it is a very helpful tool. -- CostinCozianu

I use TODO comments for things I know I'll need to fix in the next week or so (certainly before the next release). I don't like them when they stick around for a while and are ignored. If a chunk of code hasn't been touched for a while, one of the first things I'll do is find all the TODOs, review them, and delete them. -- KrisJohnson

What I like about TODO comments is that they let us put really cool-seeming ideas that are off-topic now out of our minds so we can return focus to the current task without fear of losing valuable insight. I end up deleting about 75% of my TODOs the next time I look at them because they either seem not so cool as I thought, or more obvious than I thought. The rest, I usually end up implementing within days of entering them.

As for organizing TODOs, if I have more than a handful at a time in a given app, I consider that a smell (true for me, not necessarily for anyone else). Thus, I never have enough TODOs to need organizing. I just use the Find feature of the editor to cycle through them at the beginning of a session.

-- SteveJorgensen

To me, TODO is closely related to YAGNI. "If we tweak the foo a bit, it would not just bar, but baz, bang and whiz as well!" "You aren't gonna need it (now)." "No, I know, but I'll leave a TODO." That way, YouAintGonnaNeedIt so you didn't do it right now, but you left a note to remember, so you don't feel your very precious idea will be wasted (though of course it will, when you revisit the TODO later and wonder what the $#*! you were thinking at the time).-- AalbertTorsius

[I did something very like that a couple days ago - a report relies on a very complicated nested query that runs slowly, but acceptably. At some point in the future it may be too slow, but I don't have time to re-write it now, so I included a TODO comment at the top of the page on a different technique that should be tested for better performance -- ChrisMellon?]

If you like Todo Comments, you may want to consider using a UnitTestAsTickler.