Stop Using TODO for Everything

May 2, 2022 (2y ago)

TODOs

Consider this:

You’re writing code and decide to add a feature in the future.

TODO.

You’re writing code and there’s a bug.

TODO. 

You’re writing code and there’s something that needs to be reviewed, or refactored, or noted.

TODO. TODO. TODO.

Stop using TODO for everything in your comments that requires you to do something later.

It’s not that “comments are bad,” or that “you should just use an issue tracker instead.” It’s that there’s some handy, significantly more descriptive alternatives:

TermIndicates...
FIXME:something is broken
HACK/OPTIMIZE:the code is suboptimal and should be refactored
BUG:there is a bug in the code
CHECKME/REVIEW:the code needs to be reviewed
DOCME:the code needs to be documented (either in codebase or external documentation)
TESTME:the specified code needs to be tested or that tests need to be written for that selection of code

But wait! All of these notes are still TODOs, but under a different name!

Technically, yes. But the value of using a broader selection of terms is that you (and therefore all the other programmers you’re collaborating with), are able to be more descriptive about what it is precisely that you need “to do.”

You can now filter by these more specific notes. You can even pritoritze changes based on the type of note. You can also use awesome VSCode plugins like TODO Highlight or TODO Tree to automatically highlight all of these notes.

If you can’t tell, this isn’t a super serious post. You can easily describe what you want to do in myriad ways using the classic TODO and beyond.

If you’re looking to avoid notes and comments in general, utilizing toBeImplemented() functions that either log or error with their intended eventual purpose is another great way to inform yourself and others about tasks to be completed.

And for most things, a TODO works perfectly fine. TODOs are quick and easily searchable. Just make sure you also add the task to your GitHub/Jira/Asana issue tracker (and you can even link to the issue in your comment).

Ultimately, the most important thing is that you resolve these tasks in a relatively timely manner - you don’t want your project to end up like the Linux codebase with 3000+ TODOs dating back over a decade.

But, keep in mind all of these alternatives exist - feel free to make use of them!

Thanks for reading :)

More articles