on programming Rails for fun and profit...

Tracking TODO and FIXME Comments with Rails Notes Command

This post shows how you can use the notes command in Rails to search through your codebase for comments starting with a specific keyword. By default, it searches the codebase for FIXME, OPTIMIZE, and TODO comments, but you can also configure it to use custom keywords.

rails notes command
rails notes command

When you're programming, you often run into code that needs to be changed, whether for refactoring, minor fixes, or performance optimizations. A common solution is to add a FIXME or TODO comment to come back to the code later.

However, we often forget to review those comments, which linger in the codebase. Sometimes we update/fix the code and forget to remove the notes, and now you have misleading comments. You can do a global search for the specific tags to keep track of them, but there's a better way to accomplish this using the rails notes command, which neatly lists these comments in the console.

The bin/rails notes command searches through your code for comments beginning with a specific keyword. By default, this command will search in your app, config, db, lib, and test directories for FIXME, OPTIMIZE, and TODO comments.

# FIXME: extract to a method
def publish

end

-> bin/rails notes

app/models/post.rb:
  * [10] [FIXME] extract to a method
  * [20] [TODO] refactor this method

You can also use custom keywords in the comments and specify the new keyword to the notes command using the -a flag.

# REMINDER: update gem version 
def publish

end
 
➜ bin/rails notes -a REMINDER

app/helpers/post_helper.rb:
  * [10] update gem version

Configure Custom Tags

Using custom keywords can get tedious if you have to mention them every time in the command. To solve this, Rails allows you to configure custom tags in a single place, by using config.annotations.register_tags method.

# config/environments/development.rb

Rails.application.configure do
  config.annotations.register_tags("TESTME")
end

The notes command will now look for the TESTME tag in your codebase.

$ bin/rails notes

app/models/post.rb:
  * [ 42] [TESTME] add unit test

What do you think? Do you use any custom comments in your code, other than FIXMEs or TODOs? Let me know in the comments below.

Subscribe to Akshay's Blog

Sign up now to get access to the library of members-only issues.
Jamie Larson
Subscribe