Legacy of PlayAnatomy 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:
- Indentation - Make sure your comments are aligned with the surrounding code.
- Single-line comment - Please, no blocks.
- 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.
- Your name - It should be apparent who can solve this problem, but don't make us grep the
git logto find it was your idea. Own your TODOs. - Punctuation - Whether it's a dash or not, make it consistent and put some breathing room in your comment.
- 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.
- 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.
11th of February, 2014
