Why "Consider refactoring this" comments are silly

January 6, 2022
Code is always subject to refactoring when the need arises. Adding a comment to that effect is just noise.

Yesterday I listed three causes of TODO comments. I want to call one of these types of comments out as particularly silly for teams practicing modern, agile software develpoment:

Ideas for future improvement

These comments take many forms, in my experience. Here are a few examples from real code:

  • TODO: Consider something more robust
  • TODO: Consider using dynamic imports for lazy-loading
  • TODO: Add more test cases
  • TODO: Consider adding a GetAll() method

So why do I think these are silly?

Because none of these TODO comments stands alone. Nobody (unless they’re utterly bored) is going to run into one of these and think “Gee, today would be a great day to add that GetAll() method!”

If any of these TODO comments are actually resolved, it will be in service of another purpose (i.e. “I really need some way to get all elements from this object, for this new feature I’m creating”). And in such a case, the TODO comment is entirely extraneous.

Not only that, but it should go without saying that all code is always subject to refactoring when the need arises. That’s part of evolutionary design. Adding a comment to that effect is just noise.

Related Content

TODO: Add an intriguing title

TODO comments are everywhere. And they're usually ignored. So just stop creating them.

Help wanted naming this code

Do you have a helpers or utils class or directory in your project? Maybe both? Quit it!

But we REALLY need TODO comments!

Enhance discoverability, and reduce comment rot by making sure every TODO comment references an issue number.