Automatically Annotating Model Code

In this demonstration, I will show how to set up the Annotate gem to automatically add comments to Rails model classes and other related files. We will continue to build upon the QuizMe project from the previous demos.

Something that is inconvenient about Rails model classes is that their class attributes are not defined (or otherwise visible) in their class definitions. For example, if you inspect the McQuestion model class in app/models/mc_question.rb, you will find only the following:

class McQuestion < ApplicationRecord
end

This class definition makes no mention of the class attributes, because Rails automatically adds model class attributes based the database schema defined in the db/schema.rb file.

Fortunately, the Annotate gem can help! In particular, it can be set up to automatically add comments into your model files every time you migrate the database. For example, it would add the following comments to the McQuestion model class:

# == Schema Information
#
# Table name: mc_questions
#
#  id           :bigint           not null, primary key
#  answer       :string
#  distractor_1 :string
#  distractor_2 :string
#  question     :string
#  created_at   :datetime         not null
#  updated_at   :datetime         not null
#

class McQuestion < ApplicationRecord
end

Notice how all of the model classes attributes and their types are now listed in a generated comment at the top of the file.

1. Setting Up the Annotate Gem

First, add the Annotate gem to your project by adding the following lines to the bottom of your Gemfile:

# Adds model attributes/routes to top of model files/routes file
gem 'annotate', group: :development

Next, install the Annotate gem by running the following command:

bundle install

Finally, generate a Rake task (essentially a plugin to rails) that will automatically annotate your files every time you run rails db:migrate by running the following command:

rails g annotate:install

Note that the Rake task that was generated, lib/tasks/auto_annotate_models.rake, contains a number of settings that you can customize; however, for our purposes, the default settings will suffice.

Code changeset for this part

2. Annotating the Existing Model Class

Annotate the model class we already have by running the following command:

rails db:migrate:reset

The above attribute comments should now have been added to the mc_questions.rb file as well as to the McQuestion-related model testing files.

From now on, whenever we create new database migrations and run rails db:migrate, the Annotate gem will automatically insert comments into the relevant model class files—how convenient!

Code changeset for this part