TO-DO Comments are not a Tool for Excuses
TO-DO Comments are not a Tool for Excuses…which is not to say that I think TO-DOs are bad; I think they are a useful tool for short-term reminders. An IDE can quickly search through the code and provide a list of all the outstanding TO-DOs. A build server can be configured to count these TO-DOs and fail the build if there are too many (right now, I'm thinking this should be a very small number - maybe ten or so). When I have these automated tools, I feel safe creating a TO-DO, knowing that a tool will remind me if I forget to do them.
…which is not to say that I think TO-DOs are bad; I think they are a useful tool for short-term reminders. An IDE can quickly search through the code and provide a list of all the outstanding TO-DOs. A build server can be configured to count these TO-DOs and fail the build if there are too many (right now, I'm thinking this should be a very small number - maybe ten or so). When I have these automated tools, I feel safe creating a TO-DO, knowing that a tool will remind me if I forget to do them.
The problem is that TO-DOs have a tendency to linger and fester in a codebase. Left untouched, their original intent often gets forgotten, they become obsolete, or they're too big to actually do in a single coding session. When there are too many of these TO-DOs, I start to feel bad - I cannot envision how to clean them all up, I feel like the code quality is poor, and I'm tempted to skip my attempts to make things better. So what do I do? I write more TO-DOs. These admissions of defeat replicate like a cancer and destroy the project.
TO-DOs can lurk outside of code, too: Recently I decided I wanted to blog more frequently, so I wrote a card that said "BLOG!" and put it next to my computer as a reminder. I would sit down to check my e-mail, glance at the card, feel a knot in my stomach because I remembered that I wasn't blogging ("I just wanted to check my e-mail!"), and ignore the card. The next day I'd get up in the morning in a rush to go to work, check the weather, notice the card, feel bad, and leave. This happened for several weeks. At some point I stopped seeing the card, so I threw it away and instead decided to schedule some time every week to blog. Now I feel much better, and I'm actually blogging.
So what do you do with TO-DOs that have lingered? My current plan is to look through them, prioritize and schedule the really important ones, and delete the rest. Won't I be losing valuable information that was captured in those deleted comments? Maybe, but I'm not worried about it. I always try to improve the code (see The "Boy Scout Rule"), and I'll probably have some new information when I encounter any existing problems. And if I forget to do some TO-DOs, I know I'll have automated tools to remind me.
So please - let's drop the debt, the TO-DO debt.
User Comments
I sometimes use TODO comments to indicate that I'd like other developers to replace my code with a better approach. And since I still have a lot to learn about Scala, there are often better approaches.
That's a good point, Dave. In some cases you are asking for feedback, like when learning a new language or framework. I think the dynamics change a little bit on open source projects, too -- where you don't know who might happen to look at your code and have some new information.<br><br>If that's the case, would it help to annotate those comments in some other way? Perhaps //TODOs for my own short-term reminders and //ADVICE or //RFC (Request for Comments)?
I've been in the habit of adding a priority keyword following "//TODO" (e.g. "//TODO high" "//TODO low"). I don't let the //TODO high items linger for long, but have a lot of "//TODO low" items that will probably never be touched. They just mean to me "known to be sub optimal". Sort of a lazy approach, admittedly... so: //TODO low. Use a unique tag for the "//TODO low" items.
Lately I've been putting my stories in a trac server as issues. I've been tagging my todos with the trac issue number that they are associated with. My rule is that before I close out an issue I have to go through all the todos and either do them or delete them.
@Mason My reaction to a long list of low-priority TODOs that will probably never be done is to just delete them and trust that I'll fix them when they bother me enough. Having a long list of TODOs gives me an unsettling feeling in my gut, and it's even worse if that long list of items isn't really that important (why be reminded that I have lots of relatively unimportant things to do?). <br><br>@Nick That sounds like another good strategy. Discipline and tools FTW!<br>