I was wondering what people’s standards for using tags in comments like TODO, FIXME, HACK, XXX, and the like were.

// TODO: implement the foo module here
...
// HACK here be dragons
...
// XXX
...
/* FIXME:  late at night, I need some sleep */
...

One advantage of using these tags is that they are easy to search for and give an understanding of where the code can be improved. Most IDEs even have a special view to look for these kinds of things.

My personal view is that writing a comment like these basically says that I should do something. If it gets checked into source control then it’s a problem. I should either address this right now or create a task to address the problem in the future. In the rare case that something is urgently broken, it’s best to fix it and then immediately figure out the root cause and any ramifications, when the problem is freshest. Delaying just adds a time cost to whoever tries to fix this in the future. Maintainers need to ask, “Is this still relevant or important, and how do I fix it if it is?” The second option is to put TODOs into a standard tracking system for later analysis instead. What seems urgent to fix at this time might not matter much in the greater scheme of things, so this work should be prioritized like everything else.

TODOs are definitely not acceptable for commenting out large swaths of code that break the build. The build exists for a reason–use it as a tool for creating higher quality integrated code. If your code doesn’t integrate, it’s your problem to fix it immediately. Commented-out tests are worse than useless because they add to the codebase and are not kept in sync with the main development line.

As a tangent, I usually write a date and author in comments. Even though people can use repository annotations (svn/git blame/praise), it’s much easier to see how relevant this comment is.

// AJP20021116 - I'm not sure that this works for all values of N.

Hence, if you were working on a project and saw this comment, it’s clear that it immediately is probably out of date or just not that important if it hasn’t been fixed in the past eight years. If I’m still around, future developers can ask me to recall what I was thinking.

What are your thoughts? Do you use TODOs in your code? What do you use them for? Do they make maintaining a project easier or harder?