How to Stop Shipping Code with TODO Comments

If you use Xcode, you’ve probably used or seen the TODO comment. It looks something like this:

//TODO: this isn't the most efficient. Refactor.
-(void)someMethod {
    ...
}

Here’s another:

//TODO: change to the production endpoint before shipping
#define kAPIURL @"http://staging.server.com"
//#define kAPIRUL @"http://server.com"

The TOOD commments will show up in the file’s quick jump bar, making it really easy to find them.

However, there’s nothing stopping you from forgetting to address the important TODO items before you ship. The first TODO is just that a method is inefficient. It should be looked at, but if you’re on a deadline, sometimes improving performance has to wait for a point release.

However, the second line will break your app. It cannot be shipped to either beta testers or the App Store. And there is no way to distguish between the two severities of TODOs.

Until now.

If you have code that needs to be addressed, it should be documented in more than a code comment. If it’s just a text file called BUGS.TXT or if you use Pivotal Tracker, you should be tracking what needs to be done to your code, like a gentleman. So what you want is that before you ship, you document what should be changed later and change what needs to be changed now. And now here is how you force yourself to do it:

We’re going to add a Build Script to your Xcode target to find any TODO or FIXME comments and replace them with warnings (if we’re building for Debug configuration) or replace them with errors (if we’re building for Release, as you do when you Archive).

It’s a simple script that I modified from its original source It looks like the following:

KEYWORDS="TODO:|\?\?\?:|\!\!\!:"
if ["${CONFIGURATION}" = "Release"]; then
    find "${SRCROOT}" \( -name "*.h" -or -name "*.m" \) -print0 | xargs -0 egrep --with-filename --line-number --only-matching "($KEYWORDS).*\$" | perl -p -e "s/($KEYWORDS)/ error: \$1/"
fi
if ["${CONFIGURATION}" = "Debug"]; then
    find "${SRCROOT}" \( -name "*.h" -or -name "*.m" \) -print0 | xargs -0 egrep --with-filename --line-number --only-matching "($KEYWORDS).*\$" | perl -p -e "s/($KEYWORDS)/ warning: \$1/"
fi

Just copy and paste it into a new Build Script, added through the target detail view in Xcode:

Cae77ec0dcea4032947915a76a1a1196

You’ll never ship an accidental snaffoo again because your build will break instead. While you’re developing, you’ll still have access to the TODOs as warnings, so you can navigate to them easily in the Issue Navigator.

I’m integrating it into my work flow and I’ll report back on how it works out.


Posted on August 27, 2012