Hardscrabble 🍫

By Max Jacobson

See also: the archives and an RSS feed

todo_lint: a new ruby gem to help prevent comments from stagnating

July 8, 2015

I made another gem! Here it is: https://github.com/maxjacobson/todo_lint

Last week, I wrote about required_arg, my new gem for adding required keyword arguments to Ruby 2.0.0. I actually made that, quickly, while making this one, which took several hours longer.

What does it do?

It analyzes your code and warns you about TODO comments. You can run the script automatically as part of your continuous integration (CI) build process, and it will fail your build if your TODOs are troublesome. It suggests a workflow whereby your TODO comments must be annotated with a due date, and that due date must be in the future. So you can write little notes to self in your code, but you cannot forget them, because one day your build will start failing. At that point, you can do what you’ll do; maybe you’ll snooze the todo due date into the future; maybe you’ll pull the idea out into your feature/ bug tracker; maybe you’ll just delete it in acknowledgment that you’re never gonna do it. Up to you.

It’s going to be very annoying, and hopefully that will be a good thing.

Adding it to a Ruby project is pretty simple. Here’s what it looks like to add it to a gem: https://github.com/maxjacobson/film_snob/pull/85

At work, I’m coordinating a gaggle of interns working on a new project, and I asked them to be guinea pigs for me and include this gem in their project and CI workflow. They obliged, but unfortunately it immediately didn’t work at all. I didn’t realize it, but our CI service was bundling all dependencies into the same folder as the app, and then todo_lint was checking every file from every Ruby dependency for todos. We don’t want to check all those files, because they’re out of our control. I realized we would need some kind of configuration to allow excluding by folder or maybe even pattern, so I jotted it down in a GitHub issue and told the intern to forget about it; the guinea pig was dead!

Or … was it? Awesomely, she took the time to make a pull request to todo_lint, making it user-configurable; specifically, users can now exclude file patterns like vendor/**. Excellent! The guinea pig lives.

If you’d like to help improve the project, take a look at the remaining open issues and feel free to claim one or add your own. I want my projects to be friendly toward contributors. Awesomely, bundler now suggests including a code of conduct when you create a skeleton gem with, eg, bundle gem todo_lint, and I’ll do my best to uphold that.

Join me in being a scold. It’s fun.

Note: I don't have comments or analytics on this website, so it's hard to tell if people are reading or enjoying it. Please feel free to share any feedback or thoughts by shooting me an email or tagging me in a post on Mastodon @maxjacobson@mastodon.online.