Open source tools to enhance TODO comments
I started doing a lot of research recently on existing software designed to help support developer annotations (FIXME, BUG, TODO…). I wanted to know more about use cases and pain points to find ideas on how I could improve Catana.
I found multiple tools (more than I was expecting!) and thought I would share some of my discoveries in this blog post. Hopefully, you’ll find one that suits your use cases or workflow and will give it a try!
All tools listed here are open source. I found a few paid products that I will cover in a future blog post.
If you are unfamiliar with the Javascript ecosystem, ESLint is a static code analyzer commonly used for code style but can do much more than reporting style offenses. The eslint-plugin-unicorn enhances ESLint with a set of rules, one of them being the “expiring-todo-comments”. To quote its README:
This rule makes it possible to pass arguments to TODO, FIXME and XXX comments to trigger ESLint to report.
The tool should run as part of your CI setup and will report a failure if a TODO condition is met. Built-in conditions include: a date is reached, a package is added/removed from your project, and a few more. The unicorn plugin works only on TODOs written in Javascript files.
Lots of teams and organizations have the policy to create and link TODOs to tickets on an issue tracker.
TODOs would look like // TODO Rename this function. See #151.
Todocheck is a static analyzer tool written in Go that checks if TODOs follow this convention. It will also report TODOs linked to closed or non-existing tickets. Similarly to the previous Unicorn plugin, Todocheck is best used when configured to run as part of your CI setup.
Todocheck supports TODOs written in a dozen programming languages.
Todo Or Die is a library for Ruby projects. Compared to the two previous tools, it does not use static code analysis but provides a function that gets evaluated at load time.
The concept is similar to the Unicorn plugin and is intended to expire TODOs and raise an error at a date you define. The error is supposed to fail your CI and surface the expired TODO to your team.
Almost all tools I stumbled across used the continuous integration UI as the medium to surface problematic TODOs. Breaking CI shouldn’t be overlooked as it can block your deployment pipeline, stop the workflow of your colleagues, and can be frustrating.
TodoOrDie has a cool feature that allows it to output a warning message when a TODO is close to expiring. It is optimal if you have a way to surface those warnings on your CI (e.g., you can add annotations on Buildkite that get displayed very visibly).
I wanted to highlight this one as I had a wow moment when I saw it got created almost ten years ago! It’s a proof of concept, and it works similarly to TodoOrDie.
SmartTodo is also a Ruby library, and it’s the elder brother of Catana. I created it a few years ago when I was working at Shopify. It works the same way as the Unicorn plugin and uses static code analysis to detect TODO comments and report expired TODOs when their conditions are met. The conditions are similar to what Unicorn provides but for the Ruby ecosystem.
SmartTodo was designed to assign users on TODO and notify them individually rather than failing CI for everyone. It uses Slack as the messaging platform to notify TODO owners.
I wanted to finish this post by mentioning the Python Enhancement Proposal number 350. While it’s not a tool, and you can’t use it, I thought it was worth sharing.
PEP 350 proposed to introduce codetags support into the python programming language.
The codetag term is another word used to describe developer annotations. Its author wanted to add conventions and consistency by letting developers add optional fields on their TODOs. The proposal included many fields, such as adding an assignee, an expiration date, and a priority. The goal of this proposal was to facilitate building tools to support codetags.
PEP 350 was proposed in 2005 but was rejected.
Conclusion
Seeing all these tools made me happy, and I’m grateful that their authors built and offered them to the community! I found a few other tools, but this post would be too long to list them all. Their concept was similar to what I shared, the sole difference being that they were built to work and support their respective ecosystem.
In my previous blog post, I wrote about the difference of opinions on TODOs and whether to allow them in a codebase. I hope this small list of tools will make developers that advocate for banning TODOs realize that it’s not a binary choice. With good support, developer annotations can be very helpful and allow pinpointing chunks of code.
Of course, they should be used wisely, preferably with a short or well-defined expiry lifespan, and be descriptive enough. Banning TODOs on a project is simple; creating tools to make them powerful is the real challenge.