Read more

Make "rake notes" learn about Haml, Sass, CoffeeScript, and other file types

Arne Hartherz
April 21, 2015Software engineer at makandra GmbH

Rails comes with a Rake task notes that shows code comments that start with "TODO", "FIXME", or "OPTIMIZE".

Illustration book lover

Growing Rails Applications in Practice

Check out our e-book. Learn to structure large Ruby on Rails codebases with the tools you already know and love.

  • Introduce design conventions for controllers and user-facing models
  • Create a system for growth
  • Build applications to last
Read more Show archive.org snapshot

While it's generally not good practice to leave them in your code (your work is not done until it's done), in larger projects you will occasionally have to use them as other parts of the application that you depend upon are not yet available.
To keep track of them, run rake notes. Its output looks something like this:

$ rake notes
app/controllers/frontend/media_documents_controller.rb:
  * [ 6] [TODO] should be part of a publication workflow

app/helpers/frontend/slider_helper.rb:
  * [48] [TODO] this is only temporary till frontend is done

However, with Rails' default configuration this task will only look through default file extensions, like .rb, .erb, .css, .js.

When using different markup like Haml, Sass, or CoffeeScript, you need to make Rails aware of its extensions and how comments work in each of those languages. Put the following into config/initializers/ and you are good to go:

Rails.application.config.annotations.tap do |notes|
  notes.register_extensions('scss', 'sass') { |annotation| %r(//\s*(#{annotation}):?\s*(.*?)$) }
  notes.register_extensions('haml') { |annotation| %r(#\s*(#{annotation}):?\s*(.*?)$) }
  notes.register_extensions('coffee') { |annotation| %r(#\s*(#{annotation}):?\s*(.*?)$) }
end

The block receives annotation which is a string containing a regular expression fragment ("OPTIMIZE|FIXME|TODO") and needs to return a regular expression that matches comments in the given file type. If you have other file types that you want to register, define accordingly.

Next time you run rake notes, comments in such files should show up:

$ rake notes
app/assets/stylesheets/frontend/blocks/slider.sass:
  * [ 9] [TODO] Not sure if this is correct
  
app/controllers/frontend/media_documents_controller.rb:
  * [ 6] [TODO] should be part of a publication workflow

app/helpers/frontend/slider_helper.rb:
  * [48] [TODO] this is only temporary till frontend is done
Posted by Arne Hartherz to makandra dev (2015-04-21 09:44)