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 a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.