Editor's Soapbox: TODO: Post an Article

Yesterday, I briefly mentioned the "TODO" comment as part of the WTF. Anyone who develops software for long enough is going to develop some pet peeves. Lord knows, my feelings on Hungarian Notation are well established. Or ternaries, though honestly, for ternaries, I mostly am in it for the puns.

But, I've got another pet peeve that's crawling up my butt far enough that I felt the need to do a soapbox about it.

//TODO: explain why I hate //TODO

Yes, I'm about to suggest that TODO comments should go away, or at the very least, need to be used well, which they frequently (always?) are not. There's nothing inherently wrong about leaving a TODO in code, but there are a lot of things that can go wrong with them. Enough things that go wrong that I'll just come right out and say that TODOs are a code smell.

Let's start with a "good" TODO comment, for an example.

//TODO: These weights are a first approximation. // Tune them according to real-world testing data, see (link-to-some-document-here)

A good TODO comment has to have three key things. First, it has to capture the state of the code as it is. Second, it needs to describe why it's not ideal. Third, it also describes what must be done, in an actionable way. Note, in this example, it includes a link to an external resource to find more information.

Those are the three traits about the comment itself that must be true for it to be good, but there's also a situational truth that makes a good TODO comment: it must be time consuming enough to do that you didn't do it right away, and it must be low-priority enough that you don't need any accountability for making sure it gets done.

What you see above is a best case scenario. Here are a few more realistic TODO comments culled from some projects I have seen in various places, some open source, some not, all struggling with code quality.

This first one is not so bad, honestly:

// TODO: this method WOULD work if the underlying library could handle unlimited results. This might be throwing out results? Can this be fixed?

My big complaint here is that this is a complicated task with no real clear solution- we shouldn't be tracking things like this in code. We need a task which can be assigned to someone, in some sort of task tracking tool. Yes, every single task tracking tool is garbage, and as someone who has recently started using Jira, some tracking tools are more garbage than others. But the ability to track who is working on what is important.

// dump_log(data, fname, size); // TODO: Remove

This is one of my favorite kinds of TODOs: a reminder to remove a line that's already commented out. It's almost like maybe we should have removed the line instead of commenting it out. There are folks for whom source control remains a dark art, and "commented out code that isn't dead" remains one of the main ways that manifests, and weirdly, seems to happen alongside TODOs quite a bit.

Then there's the whole class of TODOs: the appeals to ignorance

// TODO: what should be here?// TODO: verify that this is the right way to do this?// TODO: handle this thing correctly// TODO: what does status mean here?// TODO: @JoebobBobsen what is this i don't even

And of course, the apotheosis of appeals to ignorance:

// TODO: ??

At the end of the day, tracking tasks via comments in code is bad. You can't see who is working on what, you can't easily prioritize your work, and it's inconvenient to attach discussions and documentation to comments. Maybe there's a great IDE plugin out there, that lets you treat TODOs like tasks, but at the end of the day find a task tracking tool your team likes and use it. Please. Otherwise, you'll inevitably find more comments like:

//TODO: this isn't working right now. Fix it.

[Advertisement] Utilize BuildMaster to release your software with confidence, at the pace your business demands. Download today!