Todo Comments Considered Harmful

TodoComments in code is an AntiPattern. See counterarguments in TodoCommentsConsideredUseful. Only negative arguments here.

Imagine going through all those comments so that you can remember where you NeedToDoOneMoreThing?.

There are various cons:

It would be endless work. How do you know when you are done? Looking for all TODO comments in a thousand lines is no problem, but what if I have several hundred thousand lines. Do I suppose that all TODOs will be done in a week? What if it takes more?
You would be repeating the information several times: One for each place where it is produced. And take care about copy&paste. Sure I avoid doing that, but what if one of my coworkers is not as careful as I am?
Comments are usually not up-to-date. What now?
How can you organize and prioritize that information?
Suppose you arrive to this wonderful project that has several thousand TODO comments and you spent the last 2 weeks fixing some of those TODO comments. SOme of them no longer applied, but you didn't know, now your manager is asking what did you do in the last 2 weeks, but you do not remember which TODO comments did you solve. Who asked you to do that any way?

There are many solutions. The most common is a BugDatabase, but I prefer a TaskDatabase. -- GuillermoSchwarz

Or write a UnitTest. (CodeUnitTestFirst) If you don't need a test, you don't need the functionality, and TODO is irrelevant, because YouArentGonnaNeedIt.

Or write a UserStory, to be prioritized by the customer.

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

I personally never leave these comments in code since it's hard for me to get an overall view of them that way. Again, this may be an issue of tool support. (I don't use Eclipse.) What I do instead is to track future tasks in a text file or in MicrosoftExcel so I have somewhere to look them up. Never used a database for this sort of thing, though--seems like too much overhead.

Text files and spreadsheets are databases, they're not structurally relational unless you make them that way and can't easily support SQL queries, but they are databases and even have indexes. So you are using databases to track your future tasks, indexed by display position if nothing else.

: Sure, if you want to be extremely strict about your definition of database. I was using "database" in the colloquial sense, which I thought was the sort of thing that was still allowed here. Adding new rows to an Excel spreadsheet is easier than doing a SQL insert, for one thing, and sorting that stuff is mostly easier if you're using Excel for OS X, which has a pretty handy list mode. --francis

One of the things I dislike about TODO comments is what they imply about the code. They would seem to imply that there is a state of perfection to be reached with your code (when all the TODO comments are gone). Of course, code's never finished. Having those todos outside of the code seems, to me, to make it easier to imagine simply letting go of some of those TODOs ... for Rhizome my TODO list is more than 100 items long. I know that I'll never get to many of them. That's probably okay. --francis

Man, that is paranoid. I think it's always going overboard to fret about the absence of a sign of a negative. You could say exactly the same thing about a bug tracker: "what, no unresolved bugs in the database? That's bad, now everyone will be too complacent, thinking the software is perfect now.

I'm sorry, but I don't understand what you mean by "fretting about the absence of a sign of a negative"? --francis

A "TODO comment" is a sign of a negative. You commented on "when [they] are gone" as something implying a state of perfection; thus fretting about their absence.

Well, that's not what I'm fretting about. I mean, my code has absolutely no TODOs, but I don't fret about that. I'd imagine that anybody who uses TODOs heavily never gets rid of them, though the number might go up or down. (Just like my list of things to do, outside of the code, is never going to disappear, either.)

Let me try to explain my arcane, ethereal point another way ... maybe I feel that by leaving the actual note of imperfection in the code itself, I'd be kind of making a disclaimer for it. So the code you wrote was less than perfect. So what--is any of the code you write perfect? Does such a thing even exist?

I think writing perfect code is not the goal: Writing good enough code is the goal. (Though it's worth keeping in mind that what passes for good enough in most of our business is shamefully low.) How do we determine what's good enough, and how can we write code that meets that level?

Maybe I'm speaking from my experience as somebody who can be really perfectionistic about details but also wants to get things done before he dies. To my ear, a TODO comment sounds like an apology. Why apologize? At the moment you were in that code, you wanted to do something to improve it, and either you did or you didn't. If you didn't do it, you must've decided that it was not worth your time right then. Life is full of imperfect choices. Your time is always limited, the work is always infinite, and yet the universe does not collapse into entropy. It's important for me to be okay with that, and not apologizing is part of that.

Like Yoda says: "Do or do not; there is no try." --francis

I'll buy that there shouldn't be TODO notes that are apologies, but that doesn't generalize, because it's already abundantly clear that fans of TODO simply use them as reminders to do something later, not as apologies for not having done it yet.

Certainly different people use notes like this differently. I imagine not everybody has my hangup about perfectionism, and they're probably better for it.

Well, it's pretty common in programmers, but it can manifest in many different ways. It's not clear to me that anyone but an obsessive-compulsive (see TV series Monk :-) is perfectionist about literally everything in life, but many people are perfectionist about some things and not others.

Here's another thought, which might be related. When I make external notes, in a text file or a spreadsheet, I'm focusing on external aspects of quality, such as features, robustness, or speed. When I pick one and decided to act on it, I move from the outside inwards; first I try to write a unit test that fails, then I change the code accordingly. I never leave myself refactoring notes, because I try to trust that when I'll need to refactor I can just do it then.

When you make internal notes, like in-code TODO comments, are they more likely to be focused on internal aspects of quality, such as refactoring? --francis

Yes, definitely. The things that are externally visible don't need a reminder so much. The internal ones, on the other hand, can reflect a subtle insight that can be forgotten if not immediately jotted down. Hmm...maybe the true division isn't quite internal/external, maybe it's subtle versus gross. Well, clearly it's about the things that might otherwise be forgotten, for any reason.

"Like Yoda says: "Do or do not; there is no try." --francis"

TODO doesn't mean try. It means do, but not right now. Right now something else is being done. -- EricHodges

It helps you manage your GoalStack.

See, my problem is that if I ever do any sort of accounting for my GoalStack it quickly reaches a level where I literally wouldn't be able to fulfill it for decades, if at all. You have all the things you want to do, but you won't get to them all. Why write them all down? Can't you make the point that for some things, if you don't remember them, they must not be that important? --francis

Perhaps if you have a better memory than mine. I forget important things all the time, so I write them down. I only create TODO comments for things that seem important. When I revisit them later if they seem unimportant I delete them. -- EricHodges

Same here. And as for things you couldn't possibly get to within decades, those shouldn't be TODOs, because the time period implies inherently low priority. Instead, they should go into some external low priority wish list. So the answer to "Why write them all down?" is that you shouldn't -- not all of them. There's a judgement involved. -- DougMerritt

Well, it's important not to mistake Importance with Urgency. (cf. FourQuadrants) Seems to me that what's more relevant here isn't the importance of a task, but how easy it is to forget it. So what sorts of important tasks are we likely to forget? --francis

See TodoComments, EvilIsEvil.