Keeping track with Annotate

Published Feb 22, 2017
Keeping track with Annotate

Keeping track with Annotate

Now that our application is starting to get a little bit more complicated, we've friendly_id and carrierwave file uploading and association to users and our users have all the devise fields which I'm not really sure what they all are. You can start to notice that very quickly your application starts to become complicated and this is only gonna get worse as your application grows.

So there is a gem that we're gonna talk about called annotate and annotate will go through your models, fixtures, tests and so on and write a comment in there at the top of your model for example like this one:

# == Schema Info
# Table name: line_items
#  id                  :integer(11)    not null, primary key
#  quantity            :integer(11)    not null
#  product_id          :integer(11)    not null
#  unit_price          :float
#  order_id            :integer(11)

It will write a comment in there telling you what the database table looks like, so it can tell you what column type is it, what the name that thing is, as well as any restrictions on the columns so you can see that the ID column can never be null and it is also the primary key for this table. So this gem while it is not necessarily a feature for your customer or the end user on your application it is incredibly valuable for you to have this at a moments glance inside your codes so you can work much quicker.

So this is what we gonna install today, this gem is also extremely popular as it has almost a million downloads, so we will grab that line from the Gemfile and we actually want to install it inside of the development group just like we did with better errors, because this is a gem that does not really need to be available in production so we are just gonna leave it in the development group and install it there.

  group :development do
    gem 'annotate' ~> '2.6.2'


so using the annotate gem is very simple, when you are inside your Rails application all you have to do is type annotate. And this will go through and run the gem against all the models and tests and others things inside your application that it can find and it will tell you how many that it reconfigured so we can now open up our app/models/book.rb inside our application and see that we have all this comments at the beginning so we have an ID column a name, description, created_at, updated_at and so on and this is immediately available to us as we are working and it makes it for a significantly quicker development time for everything that you are doing just because you can get reference and without having to dive in anything other than the text editor you are already in. And our app/models/user.rb has been imitated as well and you can see that these are all the fields that device provides us, so we have count of how many times the user has signed in which is interesting, it is automatically shifted with device and we may or may not have known that which is really cool. So we know exactly what we are looking at here.

Now the other feature that annotate provides is annotate --routes and if you run this command it goes through and runs essentially rake routes and then it stores the output inside a comment in your config/routes.rb file, if we open up our config/routes.rb files again you can see that all of the output from rake routes in your terminal is pretty much down to right here.

So this is incredibly useful if you are not terribly familiar with your routes as you get extremely familiar with you know the syntax or this things, you will have no problem and I really need this.

So I think that's the reason why dash dash route is not done by default because it is sort just duplicating what you already see here.

Lastly annotate provides Rails integration so you can rails g annotate:install and this one install a configuration file into your application, now this is a rake file and it is a little bit different than a config initializers file so the config initializers just get wrong every single time you run the rails server.

On a rake task however when you run rake db:migrate for example that is what its happening with that.

So lets open up lib/tasks/auto_annotate_models.rake and take a look at it.

So inside this rake file you can see that the first thing that happens is that this only runs in development mode which is important because we don't really need this in production.

And it adds a task here which is all of this code that basically sets the defaults for how annotate operates and then lastly it calls Annotate.load_tasks which basically tells rake to automatically hook this and as soon as someone runs one of the rake commands that annotate it chosen to integrate with and no one that it is chosen to integrate with are essentially just the rake db:migrate ones.

So what happens is now if you are good to go into your application and run a new migration, lets generate a migration to add name to users rails g migration AddNameToUsers name and when we run this now since we've installed this rake task it is automatically found and loaded and when we run the migrations nothing changes here, however when we run rake db:migrate you will notice that not only does it add the column but it also annotates the model again as well, which is really nifty because now this is automatically updated every single time that you run a migration and now this is something that I have done manually for a long time where I run a migration and then my comments on annotate will get out of date and this integration with rake works extremely well because now I never have to remember that I need to update those because it should be always up to date.

Credits for GoRails

This transcript was written by Victor Hazbun.

Discover and read more posts from Victor H
get started