Have you ever noticed outdated // TODO: comments in your codebase that should have been addressed ages ago? 🤔
Well, how about this then:
// This will raise an error:
// TODO: 2020-01-01: This is an expired TODO comment.
Looks awesome, huh?
Let's discuss how we can do something like that.
Introducing the eslint-plugin-no-expired-todo-comments, a handy tool that prevents TODO comments with expired dates from cluttering your code.
In this blog post, we'll walk through the installation, usage, and benefits of using that tiny plugin to maintain a cleaner codebase.
Btw, the work was inspired by @parker_codes's parker-codes/todo-by, check it out too!
What is it?
The eslint-plugin-no-expired-todo-comments is an ESLint plugin that provides a new rule for detecting TODO comments with expired dates. This plugin ensures that you don't have any outdated TODO comments in your codebase, helping you keep your code clean and organized.
Installation
You can easily install the plugin using npm, yarn, or pnpm, whatever you use basically, as shown below:
npm install eslint-plugin-no-expired-todo-comments --save-dev
# or
yarn add eslint-plugin-no-expired-todo-comments --dev
# or
pnpm add eslint-plugin-no-expired-todo-comments --save-dev
Usage
Once you've installed the plugin, it's time to start using it! Simply add the no-expired-todo-comments rule to your ESLint configuration:
// .eslintrc.js
module.exports = {
plugins: ["no-expired-todo-comments"],
rules: {
"no-expired-todo-comments/no-expired-todo-comments": "error",
},
};
Now, whenever you have a TODO comment with an expired date in your codebase, ESLint will raise an error, prompting you to address it before moving forward:
// This will raise an error:
// TODO: 2020-01-01: This is an expired TODO comment.
As simple as that!
Benefits
By using eslint-plugin-no-expired-todo-comments, you can:
- Keep your codebase clean and organized by removing unnecessary and outdated TODO comments.
- Ensure that your team stays on top of tasks, as expired TODO comments will now trigger errors.
- Improve code quality by addressing TODO comments in a timely manner.
Contributing
The project welcomes contributions from the community! If you encounter any bugs or issues, please open an issue on the project's GitHub page. If you'd like to contribute code, please fork the project and submit a pull request with your changes.
Conclusion
In summary, the plugin above is a useful tool for maintaining a clean and organized codebase by preventing outdated TODO comments. With this plugin, you'll never have to worry about forgetting or neglecting important tasks buried in your code.
And finally, a little programming joke to wrap things up:
Why do programmers always mix up Christmas and Halloween? 🎃 🎄
Because Oct 31 == Dec 25! 😂
Happy coding, and may your TODO comments never get forgotten again! 😉
P.S.: If you liked this - you might like some other things I've done recently:
AI-powered changelog updates on Slack, every Monday, with GitHub Actions
Follow me on Twitter: @MaxPrilutskiy
Top comments (7)
This looks great!
Unfortunately, sometimes it's project planning/time constraints that prevent us from finishing off a to-do. For example, I've been in situations where I've been rushing to get something done for the end of a sprint. I put in a note to say that some code has been hacked together and that it should be done properly. However, I wasn't given time in the subsequent sprints to address the issue as other things had higher priority.
That sucks, man! I feel you, been there too. It's okay to reschedule though.
On the flip side, I've seen many cases in the past, when we were delaying some stuff because we were waiting for a 3rd party library to update, etc, etc.
Or, when we have to upgrade a piece in our code at some point, because of some deprecation happening in the future that we already aware of.
Just some cases when an expiring TODO helps to keep stuff organized and under control, but there are def more of them.
I can see that an expiring TODO would definitely help. The fact that an expiry date keeps popping up would probably make me bring it up repeatedly during sprint planning. Even if not, it'd act as a reminder for the little bits of downtime between sprints.
Simply don’t do “TODO” in your code if there is no real, real, big, good reason for it!
In most cases, you will never do the “todo”, as long as it works.
You will find your todos years later in the code base, no one will have an idea what exactly needs to be done.
If “you hack” something, only to reach a sprint goal - you probably do something wrong. Because the ticket is not done in this case, if you need to work on it again 😜.
It’s only hiding “did not complete the task” from others.
Keep you code clean and implement stuff properly once, instead of mess up code with lot of future maintenance.
If there are parts where you have follow ups. Then you can add a Todo comment with a ticket number (jira/GitHub issue…) to your code and throw something like “not implemented”.
The ticket should exactly describe what needs to be done.
This way it can be picked up by someone else and added to plannings and sprints properly.
This way the ToDo is only a simple back-reference in your code to find the right code lines and to signal to everyone “aware of it, planned…”
That'd be the ideal state of the codebase!
Unfortunately, in reality, oftentimes, you see codebase in between such "ideal" states, and that's where TODOs are helpful.
Ultimately though, I'd even say that comments is a an anti-pattern: it's easy to write code that is self-documentary already.
But overall, that's a really good overview, thanks, Sebastian! Makes total sense.
by changing the TODO expiry date
🤣
Some comments have been hidden by the post's author - find out more