Monthly Archives: December 2008

TODO or not TODO

Are TODOs in source code good or evil?

In my view, TODOs are a tool and like any tool, it can be misused. I do agree with most of the critism but if they are used with care and if they are actively managed they can improve productivity.

Sure, TODOs tend to accumulate and, yes, there are selfish developers who use them to acquit themselves from checking in sloppy code (which they will never clean-up). Yet, there are situations where they are appropriate.

Sometimes it just makes sense to check-in code that is not 100% done. For instance, if all of your requirements are not settled yet or you are uncertain about some boundary cases. Here is my litmus test: if your unfinished code already provides value to somebody else and it doesn’t break existing tests it is OK to check it in. Be it a tester who needs a running system to develop test cases against or a coder who needs your class to continue her work. Maybe it’s a sales person who needs a quick tentative solution for his trade show. Unfinished code is especially appreciated in the ‘bazaar’ software development model.

If you accept the notion that unfinished code is useful if it already provides value, you probably also agree that it is not a good idea to keep the list of open issues in your head; even scrap paper is only slightly better. To me, it is much better to record ‘tentativeness’ very close to the code.

However, it is essential to manage those TODOs — if you don’t manage them, they will eat you alive.

In order to manage you need to track, and tracking is much easier if your TODOs follow a standardized format. Once you have a standardized format you can easily extract metrics. If everybody used their own style of TODOs it would be very hard to control them. A mix of TODO, FIXME, BUGBUG, ???, ### is TODO hell.

After years of experimenting, I’ve found this style of TODO comments to be the best:

Let me briefly describe why I consider this format to be superior.

First of all, it starts with ‘TODO’ in all capital letters, which is good, as it is recognized by many editors/IDEs and highlighted in a special manner. This makes it easy to recognize TODOs for human beings when browsing source code.

Next comes the date in ISO 8601 ‘extended’ format. Not only does this tell you when the TODO was added: it allows you to easily sort your TODOs:

The sorted output will show you which TODOs have been around for a long time, maybe for too long a time.

After the ISO date comes the name of the TODO owner. I suggest you use login names, but it doesn’t really matter as long as it is unique and can be easily mapped to a real person’s name. Due to the fact that the name is surrounded by colons you can build a list showing who owns the most TODOs:

Finally, there is a brief summary that describes the reason for the TODO; if necessary, additional text follows on the next lines. Describing a TODO is essential: it tells developers why it is there; leaving it out is akin to putting up a ‘Watch out’ warning sign without giving any additional clues.

In order to extract information automatically, the standardized format must be enforced. This grep command will catch most ill-formed TODOs:

In addition to pinpointing typical TODO comment keywords it ensures that the date is well-formed and that the owner and description fields are not omitted.

Ideally, you run such scripts automatically every time a developer checks-in changes. If you don’t have testbots you should at least run them as part of your daily build procedure. In case you don’t even have daily builds (pity you!) it is the job of the project lead to execute them regularly.

TODOs are useful for modern, release-early-and-often software development processes; by standardizing their format, all of the common disadvantages can be overcome. If you don’t use them yet, I suggest you put them near the top of your TODO list.

Tools I Carry

I recently wrote about the most important tools of a software developer. The tools that I mentioned are important to be a successful developer — they are not sufficient to master the other challenges of life.

Being the geek that I am, I carry all sorts of things in my pockets — things I couldn’t live without. Today, I’ll do a headstand and show you what I’ve got.

First of all, there is my swiss army knife. I need it for all kinds of situations: tightening screws, cutting of loose threads on clothing, opening bottles. Last spring we went on a hiking trip and my son got bitten by a tick — I used my knife’s tweezers to pull it out. It’s amazing: once you carry a swiss army knife, all kinds of occasions arise to use it and you wonder how you could have survived so far without it.

But I had to make a trade-off: naturally, I wish to have as many functions on my knife as possible: many screwdrivers of different shapes and sizes, a magnifier, scissors; and it should have a big blade such that its possible to cut off a slice of bread from a big loaf. All of this is available from Victorinox and Wenger (they even have knives that come with LED lights and USB memory). Alas, there is only limited space in my pockets! I certainly don’t want to carry a brick around. After years of experimenting with various models, for me, the Wenger “Evolution 10” is the best compromise. Always remember: the best knife is the one that you have on you; a 30+ function knife is of no use if it’s left in your cupboard.

I also need to have a pen on me. Not just an ordinary five cent plastic giveaway pen that might leak ink or run dry. Typically, those pens are also too big to carry them in your pants pockets (I rarely wear shirts, so all my tools need to be placed in my pants pockets). I prefer the famous Fisher ‘Bullet’ Space Pen. This pen is just so cool, so small, so sleek, so robust, so timeless. It comes with a special pressurized ink cartridge that allows you to even write up-side-down — on wet paper, if necessary.

Speaking of paper: a pen — even a Fisher Space Pen — is of little use without paper (unless you are willing to write on your palm or the back of your hand, something I do only in extreme situations). I’m a big fan of Moleskine notebooks and I would love to have one available everywhere I am. Unfortunately, even the small version is too big and heavy to carry in a shirt or pants pocket. By contrast, my ’emergency notebook’ is quite lightweight: a folded A6 index card, which gives me four pages of about 10 cm x 7.5 cm. It’s not much — but it is something!

Whether there is something to fix or an idea to be jotted down, with my tools I can rise to the occasion; I wouldn’t even think about leaving my house without them.