TODO comments are not clean code. Use them correctly!

I have realized TODO comments should not be part of the production code. They can be practical in the development process. There is an option to configure an ESLint rule to avoid them. The following article explains the way how to work with these comments.

Fixing Something Later

A mindset of fixing later is not correct regardless of whether you decide to insert a TODO comment or if you just try to remember it. How often do you get back to that particular piece of code the first moment you get extra time after releasing the feature? And how much do you decide to fix the code right away when you discover a TODO comment? You have my respect if your answers are “often” in both cases.

I don’t want you to get me wrong. There can be a situation when a project needs a quick solution, and there are no resources for the cleanest code. However, it is necessary to differentiate between a code that can “stay” and a code that needs urgent improvement (a known bug fix). What this improvement actually is? It is a new task, and there is no reason to not track this work in our task tracker: GitHub Issues, Jira, etc.

But not all TODO comments are wrong…

Notes for Development

My advice is not about avoiding TODO comments at all. I would like to share how to use them differently. TODO comments are not ideal for task tracking, but they can be significantly helpful as notes during the development process.

Let me give you another example. I’m working on a task. I want to start with creating a prototype to know the actual problem first. I’m uncertain about the most performant database call, but the performance is not that important for me at this stage. I just simply write a TODO comment next to the database call. In the end, before a code review from another person, I make sure my code does not contain any TODO comments.

Make sure… How to not forget about that?

ESLint Rule

In my opinion, ESLint is the best JavaScript tool. The tool really helps with code quality checks. There is also a way how to configure ESLint for checking TODO comments.

The rule is part of the official ESLint set. It has name no-warning-comments. This rule checks all comments, and you can specify specific words that will be marked as an error. The following code can be your typical rule configuration:

// .eslintrc.json
module.exports = {
  // Other ESLint configuration...
  rules: {
    // Other ESLint rules...
    'no-warning-comments': [
      'error',
      {
        terms: ['todo', 'fixme'],
        location: 'start',
      },
    ],
  },
}

This configuration marks these comments as error:

// TODO - I was very lazy here...
/* todo: Impossible to read but it works ¯\_(ツ)_/¯ */
// fixme please

And you are still allowed to use this word in specific cases:

/**
 * Returns all TODO items for current day
 * based on JS Date implementation.
 * @returns {Array<string>} tasks
 **/
function getTasksForToday() {
  return []
}

This is all you need to know. Try to configure the ESLint rule. Work with your task tracker instead of TODO comments. I’m sure your code will be cleaner. In any way, please share your experience in the comment section below!