TO-DO Comments are not a Tool for Excuses

[article]
Summary:
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.

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

5 comments
Anonymous's picture
Anonymous

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.

May 10, 2009 - 12:24am
Anonymous's picture
Anonymous

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)?

May 10, 2009 - 12:33am
Anonymous's picture
Anonymous

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.

May 10, 2009 - 1:22am
Anonymous's picture
Anonymous

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.

May 10, 2009 - 1:27am
Anonymous's picture
Anonymous

@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>

May 10, 2009 - 1:39am

About the author

AgileConnection is one of the growing communities of the TechWell network.

Featuring fresh, insightful stories, TechWell.com is the place to go for what is happening in software development and delivery.  Join the conversation now!