Stop Ignoring TODOs: A Guide to Managing Comments in Your Code

When TODOs pile up like sticky notes, it’s time for a cleanup

Imagine you have an idea or thought related to what you’re doing but can’t take care of it at the moment. You jot it down on a shiny Post-It note and stick it to your desk. This happens regularly while you work (or live), and your desk slowly becomes cluttered with sticky notes. Every now and then, you process some, but you add new ones at a much higher rate than you remove them. Soon, you have notes you barely remember the purpose of, yet you’re scared to remove them in case you might need them later. Eventually, you become sticky-notes blind and just ignore them as they bring no value anymore.

Sounds familiar?

And what if you’re a software developer using TODO-prefixed comments in your source code instead of sticky notes? Don’t they accumulate in your codebase in a very similar way? Are they all still relevant and up-to-date?

It feels like there is a natural law saying that in a codebase existing long enough, comments like this one evolve:

// TODO temporary!!!

being there forgotten for years. Or classics in bad comments we all wrote at some point. Yes, I mean:

// TODO improve

and the minimalist’s favorite:

// TODO

And, of course, all the comments not understandable to anybody, including their author, assuming they haven’t left ages ago.

Here are battle-proven tips on how to approach your source code TODO comments so they actually do bring value.

Disclaimer:

This post is not about best practices in writing code comments. You will find plenty of useful articles on this topic; for some I especially like, see the sources at the end of this post.

I focus purely on so-called TODO comments. By ‘TODO comment’, I mean a comment prefixed with either the ‘TODO’ or ‘FIXME’ keyword. I dare say this post is relevant for all programming languages.

Clean up the mess!

Let’s see what to do if your codebase is already cluttered with TODOs and you have no idea how to act upon them.

First, to enter the era of useful-todo-comments in your codebase, list all TODO comments and proceed using the following rules (your IDE can list them for you). Don’t hesitate to be ruthless. If the TODO wasn’t resolved until now, there is little chance it will ever be resolved and only clutters your code, making relevant TODO comments less prominent. Moreover, they are forever stored in your version control in case you ever need them.

Better to have no TODO comments than comments nobody ever bothers to resolve.

1. Remove all comments you don’t understand.
2. Remove all comments that are no longer relevant.
3. Move to your backlog all comments that must or should eventually be implemented. They should be stored where your planning happens, not in your codebase.

Rewrite all remaining comments in an actionable way with a clear, measurable outcome to simplify their resolution (whether by you or anyone else). Remove the ‘TODO’ prefix. There should be only few remaining. If not, you likely weren’t ruthless enough.

For example, instead of this:

// TODO check if this is correct

prefer this:

// TODO: Verify method handles null inputs and unexpected characters.

Don’t know how to rewrite the comment? Then you don’t understand it and should remove it.

Done!
Tap yourself on the shoulder; future developers will be thankful 🙌.

How to prevent mess from growing (again)

Any cleanup is only a temporary pain relief and not a solution if not followed by a strategy to prevent future mess from growing again. This is true for our houses, lives, and… codebases.

In the context of codebases, the strategy is straightforward:

👉 All TODOs should be resolved before changes are merged. 👈

Code review is the process that should catch all remaining TODOs. You should either resolve the TODOs in a similar way as when doing the cleanup described above 👆

• Act upon the TODO if it fits into the scope of your current work OR
• Move it into the backlog OR
• Rewrite it as a suggestion for future improvements, explaining why and why you haven’t done it yourself OR
• Remove it

For strategies for houses, read something from Marie Kondo. For life… well, good luck.

And never use a TODO comment as an excuse for code you write and are not happy with. Comments like

// TODO this should be improved

are nothing more than an excuse. Either improve it right away or write a suggestion on how to actually improve it in case there is not enough time to do it. And either plan it according to your priorities or just keep it there without TODO.

Why without TODO? Well, because if it is okay not to plan it or to implement it right away, it is just a nice-to-have thing you can live without. And our codebases are and never will be perfect. Admit it.

But having a note for a future developer with some spare time and energy to do some refactoring is helpful.

Happy coding.

Sources

You can find plant of resources how to write source code comments in general. For example Write a better comment is one I like.