TODO: FIXME, HACK, and XXX
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?
next post: Pecha Kucha Complaining
I use TODOs in my code for two reasons. I personally only advocate it for one reason though.
Many times I like to, while cranking out some code, slip a couple TODO’s in when I have a thought, but am not ready to write that code yet. I do this usually only for thing I know I’m going to resolve in the short-term (<30 minutes). It helps me keep my train of thought and to stay in flow. I don't have a problem with these going into my VCS as long as it stays local (ala git, etc.).
The other reason is for a long-term "this needs to get done at some point" type of thing. I usually do this because it's less friction than creating a new work item in my current work item tracking system. That being said, a date can be useful, but initials and a reason/context are a must. Otherwise, the next time I'm in there and I see your TODO's, I'm gonna rip them out and assume it's done.
I use ‘em all the time. If I’m in the middle of implementing a feature and I have to fork my thought process, I stamp down a TODO. I check them in, too. But, you know, I don’t consider a feature delivered until all of that nonsense has been resolved. I do remove them. (Yes, I check in incomplete features. Yes, I still consider them production-quality.)
There was a day way back when I was a hardass about driving them out of production checkins. It was very black and white, and I said all the same things you did. There is often definitely a more appropriate places for that info. The code is not an issue tracking system.
If you’re going to have them, I think you need a standardized tag like “TODO”, not just “MBA20100118″. (MBA 1/18/2010 is better for those of us without positronic brains. :p)
BTW, if you’re experiencing a difficult with TODOs, I’d like to offer that TODOs aren’t the problem as much as a symptom.
It’s late, and I don’t really know how to say this in a diplomatic, fair, plus-plus manner right now. So I’ll just say it and hope I don’t sound like a complete jerk.
IMO, if a system is rife with TODOs, it’s a symptom of one of these:
1. No acceptable outlet for the information.
Either there’s weak/no source control, weak/no issue tracking, weak/no documentation practice (design docs, design notes, KBs where appropriate).
This is fixed by a champion or management taking time to put one in place. Training might not even need to be involved if it’s a tool people are already used to that’s just not present.
2. A vice among the developers, whatever their experience.
Specifically, it will be one of these related items:
* Not thorough — Habitually only checks the happy path on things, doesn’t do well with details, forgets to go back.
* “ADHD”-ish — Their thought processes show more signs of (uncontrollable) diverging than than converging. Seriously, these people are confused in code and probably should do something else for a living.
* Can’t finish — Likes to start tasks and move to interesting work. Cheerfully declares a task done before everything’s checked in, passed tests, passed the build, has a deployment script, or has been marked in TFS. Usually just forgets this stuff when thinking about his remaining work, even if he’s normally very good about details.
* Unaware — Hasn’t really been exposed to the problems of a practice, or of not having and following a system for doing things. Will continue to act this way until he can see the connection and believe there’s a consequence. Like “We put our open issues in TFS, not the code, because that’s where we look when we do our weekly review. So stop using TODOs for this.” IMO, this is the most rewarding vice to help someone with.
* Maybe others — Like some people habitually make things more complicated, but they may or may not be TODO mongers.
… and from experience I can tell you that yelling with “WHY CAN’T YOU BE MORE LIKE PINCHES?!?!?!” doesn’t help.
I’m not saying these people need to change or anything. Bending the spoon is an exercise left to the mentor.
It’s more of a style thing, but since I’ve escaped from the land of Eclipse, I’ve basically stopped using TODO’s. I’m kind of addicted to issue trackers though, so I understand why others might want to put simple notes that aren’t full-on tasks in code comments.
Thanks everyone for commenting! I tried to draw a hard line to see what sort of reactions people had, and it seemed like this was successful. This post stemmed from some work that I was doing and was puzzling over when I thought that I had, myself, written TODOs into some code on my previous project. So I was trying to see what other people thought. I tend to agree with what you guys said, in that if there’s a comment that it should be temporary or very clear to future maintainers in terms of scope.
The biggest problem, after thinking about it some more, is that there is no responsibility. TODO doesn’t yell “you, right there, take care of me.” It just hangs out until the next hapless adventurer wanders nearby, probably to be ignored. Even when the TODO is implemented, there are no references to it, so it becomes out of date with what actually needs to be done.
One of the other reasons I was interested in writing this was that perhaps by challenging an unwritten or unacknowledged assumption, that people might reexamine this habit because it might make their code harder to deal with. Everyone has seen their lead engineer use TODOs around the codebase, so it “must” be a good practice. And hence generations of programmers learned this trick, like the little girl who cut the end off a perfectly good ham because her mother did it. In reality TODOs are an anti-trick if not done well.
Late comment, but.
I don’t use TODOs, XXXs, FIXMEs, or anything of the sort, and encourage people I work with to do the same.
Those are items for to-do lists, which I do not think belong in source code. Source code should strive for algorithmic and structural clarity; it shouldn’t be littered with meta-comments about why some developer thinks some code block could be fixed up.
If people want to know what’s going on with a certain block, and what work might be scheduled for it, it is far better to accomplish that with (1) detailed commit messages linking to (2) issues in a project management system and (3) developers disciplined enough to maintain (1) and (2) over the course of a project.
I do use both: TODOs, XXXs, FIXMEs as well as a ticket system.
First reason: It is easier to find the code for a ticket.
Second reason: Not everything is worth to create a ticket for. Well a FIXME is always worth it, but “XXX a very long method” is not (or you do not have enough TODOs)