In Defense of TODO Comments
Despite all the negative press, TODOs in comments are actually great. They let you make a note directly tied to a location in a source file without requiring you to switch context to another app or otherwise interrupting your train of thought. They essentially allow you to tag the code you’re working on with an action item or reminder for later.
On the other hand, everyone is right that they suck. They don’t scale at all beyond one developer. Too many can be overwhelming even for a single developer to tackle, let alone a developer new to a project who is just learning the codebase. They can be forgotten in long untouched code. They can be deleted accidentally. After many edits to a file, they may be moved or disconnected from the code they were originally attached to, making the original meaning unclear.
Despite these flaws, they are very conveient and do initially increase productivity by allowing a developer to stay focused on the problem at hand. For that purpose, they are tried and proven. The only problems arise when the TODO items need to be accessed at a later point.
Luckily there is already a solution, at least for JavaScript and Node.js developers: the ESLint no-warning-comments rule. With the proper tooling TODOs in comments are awesome. A developer can use them in their own branch without interfering with other developers’ productivity. An automated process can prevent the comments from making it into master or develop branch. If ESLint is already a part of your continuous integration toolchain, it is easy to enable this feature. If ESLint isn’t yet part of your toolchain, why isn’t it?
I’d like to see support for TODOs in comments taken further. What if a pre-commit hook or other automatic script were used to strip out TODO comments from code committed to source control? The script could then make a GitHub issue containing the text of the comment and a link to the source code locked to the commit and line number of the removed comment.
Really, the hubub against TODO comments is a failure of the software developer community at large. We often allow combative and vacuous rants to drive us, rather than seeking a sober look at the current state of a practice or technology. Isn’t it time this type of mentality is finally laid to rest as “considered harmful” itself?
Sometimes problems are really opportunities. In this case, we need more and cooler linters not more “considered harmful” rants!
I haven’t blogged in a while, and I have to say it feels good to write again! My next article will be about Baucis2, an open source project I created. If you’d like to help Baucis2 development, please donate here: https://www.gofundme.com/baucis2
