Why I Stopped Using To-Do Code Comments

I used to put To-Do comments in my code pretty frequently. I'm sure most of us have done it at one time or another:

//TO-DO: clean up this logic

It's a quick and easy way to make note of something you need to go back and fix later. It certainly has the advantage of keeping you right in the code editor and not disrupting your flow while you're working on a project.

However, as I've moved into projects with greater levels of complexity and collaboration, I've found this approach just doesn't scale well for me. I've largely stopped using To-Do comments to keep track of things to go back and fix in the future. Here are some reasons to consider doing the same, and what I now do instead.

Hard to Track

Keeping track of all these across a growing code base becomes a challenge. Did I use "TO-DO" or "TODO"? Is everyone on the team following the same conventions?

There are options like the TODO Highlight extension for Visual Studio Code that can help with this, but by and large, it's going to be a challenge to effectively keep tasks organized and discoverable as the list grows.

Out of Sight, Out of Mind

Once a release is pushed out, it's easy to forget about these to-do items scattered throughout the code, not making time to go back and revisit them later. Without a clear location to compile a list, these tasks aren't likely to get the priority they deserve. Many of us have been in situations, either with our own code or someone else's, where we've found very old to-dos in the code that just never got fixed.

I've been there myself, with that inner voice in the back of my head laughing at me as I put another to-do into the code that is unlikely to be addressed.

No Prioritization

If you ever do make time to tackle these to-dos, which ones are most important? Are there any dependencies among them? Every comment is essentially going to hold equal weight. These comments tend to be quick so that we can get back to coding, so there's little in the way of in-depth explanation, justification, or prioritization.

In the event that we actually do get time to go back and address these later, it's going to be an additional time-consuming task to gather them all up, evaluate any dependencies, and prioritize the work effort.

The Alternative: GitHub Issues

Instead of writing to-do comments, I've largely switched to using GitHub Issues, even on small personal projects where I'm the only person committing to the repository. I've found this to be a much more elegant method to keep track of things to go back and fix.

For starters, you get a single source of truth. No longer is it difficult to track to-do "conventions" across a code base. Everyone knows where to go look for to-do items, which is very important as team size and lines of code scale. Someone who is in management or works on a code base infrequently can very easily see the outstanding fixes without having to investigate the code itself.

Dovetailing with the single source of truth is the high availability and visibility of the issues list. To-dos don't get memory holed after a release. The issues remain front and center in GitHub and have to be dealt with one way or the other. Closing one out without addressing it requires a conscious decision and action.

The problem with prioritization is also smoothed out by using GitHub. Issues can all be seen and prioritized in one single location. This is also useful when making a business case to allot time for issue resolution before moving on to the next project, because decision makers have full and easy access to the issue list.

Most of all, though, I find that using GitHub Issues allows for much better contextualization of issues. Relevant code snippets, links to external resources for troubleshooting such as Stack Overflow, and screenshots of an issue reproduction can be embedded. Descriptions of issues can be longer than anything that can reasonably be put in a code comment, making it easier to remember the details of the specific issue and what needs to be done weeks or months down the road. Issues can also reference other issues, an they can be tagged and classified to further help with the aforementioned prioritization tasks.

There's even more to unpack potentially, such as opportunities for automation benefits using GitHub Actions. The above improvements I've seen personally really only scratch the surface of what is possible.

Summary

If you aren't using anything more than comments to track to-dos, I'd highly recommend giving GitHub Issues a shot (or GitLab, Bitbucket, etc. if you use a different source control system). It's easy to give it a try on a small personal project to see if you like the workflow, before trying it out on a larger project.

Do you have another preferred way to track the to-do list in your codebase? Let me know in the comments below, or on Twitter.

Enjoyed this post? Consider buying me a coffee to fuel the creation of more content.