Task Management in Source Code

I often see something when I am looking at source code, that I will need to address to get to where I am planning on going, but that for whatever reason, I don’t want to write at that particular moment.

Instead of popping out to another tool to record that, I just toss in a comment right where it would be relevant. This has several benefits, the first such being that the task, a “TODO” if you will, is in context. A reminder of what you were thinking the last time you looked at a segment of code is plopped down right smack in front of you when you visit again.

Another benefit, derives from YAGNI, meaning “You aren’t going to need it.” This is a popular idea that you should not overburden your code so soon, as is a core tenet of the Agile programming methodology, along with DRY (don’t repeat yourself) and the entire iterative development process.

If you make a TODO comment, and it turns out that YAGNI, the perceived problem never develops, then you never return to it, but it’s just a line of wasted text, at about the minimum effort expenditure possible for a coder. Plus, you may have a clue when you try to purge your TODO file (see next section)

Another benefit, is that you can put some of your tools to work for you, and easily gather all those scattered TODO items into one place. Here’s the dead simple rake task I use to do that in my current rails project :

desc "Extract TO DO items from comments in source code"
task :todos do
  sh 'grep -r "# TODO" . | grep -v "\.svn" | grep -v "vendor/plugins" > doc/TODOs.txt'
  # check-in updated To-Do list for project
  sh 'svn ci doc/TODOs.txt -m "Updated TODOs extracted from comments in the source code"'
end

Just a couple of things to note here. The grep task looks for a specific comment prefix ”# TODO” so you have to establish that as your habit. Also, you’ll note that I ignored matches from plugins, as those are not necessarily my tasks. Those separate projects can get their own TODOs.txt file just as easy!

Finally, I check in the updated text file, giving me a history of what I thought needed doing when. If you run this task a couple times a week, you can build up a history of what got checked off.

Of course, this is a very “low tech” method, but if I keep enjoying this methodology, I’ll increase the sophistication on the backside, and let you know how I extend it.

Posted by Phi Sanders on Wednesday, May 07, 2008