Anatomy of a Schoon TODO

In its original Dutch, my nickname, Schoon, means "clean". Doubly-appropriate, perhaps, that my method of TODO comments be called a "Schoon TODO" by former colleagues. It's the cleanest I've seen.

Quick disclaimer, perhaps: I don't know this style to be unique, but I don't know it not to be unique. I've never verified either way, so I won't assert either to be true. Just take this as "the way I do things, and maybe that's helpful."

Here's a sample, simple, real-world pair of TODO comments in code I just wrote (and which prompted this post):

// TODO(schoon) - Validation.
// TODO(schoon) - Ensure the appId (at the least) is unique?

To break this down, there are seven important components to these comments:

  1. Indentation - Make sure your comments are aligned with the surrounding code.
  2. Single-line comment - Please, no blocks.
  3. TODO - Not FIXME, not HACK. At best, these mean different things. At worst, these confuse people. For example, I use HACK to indicate something that needs to change without indicating how, and I never use FIXME.
  4. Your name - It should be apparent who can solve this problem, but don't make us grep the git log to find it was your idea. Own your TODOs.
  5. Punctuation - Whether it's a dash or not, make it consistent and put some breathing room in your comment.
  6. Details - The most important part of the comment along with the rest of the comment. Provide enough detail to remind yourself what needs to be done: no more, no less. If there are a lot of details, use your bug tracking software. TODOs are for little, immediate notes.
  7. Punctuation - This is almost the most important little detail. A period indicates this is a concrete, sure TODO. A question mark indicates you're unsure, and more thoughts and discussions should follow.

I wrote both of these in a two-space-indented block of code, and I'm unsure if or how appId needs to be unique. It needs to be properly-formatted as an appId, however, so that validation needs to happen. But that's enough analysis - go forth and make your TODOs more useful.

More Posts