// TODO Comments Are a Joke, But They Don’t Have To Be
Have you ever come across a TODO comment in some code and had a chuckle? Maybe it looked like: // TODO fix this, with no context. Maybe it was added years ago by a developer who’s quit the project. Or better yet, maybe you added it yourself and haven’t given it a second thought since.
TODO comments are a low overhead way of saying “hmm, this isn’t perfect but I’m going to move on for now and hopefully make it better in the future.”
They come in a variety of forms: FIXME, HACK, OPTIMIZE, and they’re baked into the programming habits of enough developers that many IDEs come preloaded with support for finding and displaying them.
As the creator of tickgit, a tool that uses TODO comments to help developers do project management, I’m certainly biased towards the general use of TODO comments, and I hope for good reason.
Low Overhead
TODOs are easy to add and remove. They’re plaintext, and as such, fairly flexible. You can link to a ticket, write an extra-long comment, include some ASCII art, use emojis, whatever. Sometimes less is more, and plaintext can go a long way.
No Context Switch
TODOs are right in your code, next to what they’re typically describing. You don’t have to switch contexts between your ticketing system and your code or follow breadcrumbs from one to the other. If you’re working on a train of thought in your code, comments are there to help remind you of what you’re working on — what needs improvement, what’s already implemented, what can be modified or done better.
Sometimes it’s hard to grasp all of this from an external ticket, and doing so can require a thorough copy of your code’s context into that ticket. Moreover, this context might change over time, and your ticket may become stale.
Have a History
TODOs can be checked into your VCS and as such, have a history. They can be blamed, code-reviewed, and treated as any other line of code or comment in your project.
Four years ago, so-and-so left
# OPIMIZE we can speed this up by doing …and now that we’ve reached some scale, it’s a good time to implement. Good thing she left some notes!
CI/CD
Since they’re a part of your source code, you can apply CI/CD tooling on them just the same. In fact, tools out there already do this. Don’t want TODOs in master? Want to ensure they follow a format? (i.e. have an assignee — // HACK (patrickdevivo)) Maybe fail CI if they’ve been in the code for longer than X days? These are, of course, up to you and the preferences of your project.
Can be Used Any Way You Like
Because of their simplicity, flexibility, and equivalency to code comments, you have a lot of freedom with TODOs and “rules” around them. This may manifest in habits or full-blown policies and procedures enforced via CI.
Even the Pros Use Them
Some big projects use them in various ways, to varying degrees of rigor. Some require every TODO to be tied to a ticket with an assignee/point of contact.
So What’s the Joke?
The joke is that many TODO comments are forgotten. They’re cast aside by encroaching deadlines, shifting priorities, context shifting, and all the other ailments that can erode an engineering team.
Just look at the average age of many of the TODOs in the links above. If someone leaves a note and it remains untouched for years, is it worth saying anything at all? How can we be better at managing TODOs? Should we even bother?
(this is the part where I shamelessly plug my project)
My hope is with a tool and a service like tickgit.com we can better grapple the “always in motion” nature of our code. Better tooling can unlock better practices and hopefully better software development. Regardless of how you use TODO comments, I hope you can find value in using something like tickgit to proactively surface them and keep tabs on your technical debt. Sometimes a bit of UX and DX can have an outsized impact, and I’d love to develop this project into an effective tool that helps us all maintain better code. So please reach out if it resonates with you, if you have suggestions, or for any other reason!
But // TODO is a Code Smell!
IMO, TODOs are inert. They are a tool that can be used either effectively or not. If you consider them bad practice, I would suggest considering what you see as “bad” — the TODO itself or how they are made use of (or not)?
And if they are a code smell, maybe some policy and CI integration can help?
P.S.
Check out imdone.io for another interesting project helping developers do project management with TODOs.
