Resources

Transcripts

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:

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:developmentdogem'annotate'~>'2.6.2'end

bundle

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.

Now that our application is starting to get a little more complicated, we've got FriendlyID and carrierwave file uploading, and the association to users, and our users have all of the devise fields which I'm not really sure what they all are. You can start to notice very quickly that your application starts to become complicated, and this is only going to get worse as your application grows, so there's a gem that we're going to 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. It will write a comment in there telling you what the database table looks like, so you can tell what column type it is, the name of the thing it is, as well as any restrictions on the column, so you can see that the ID column can never be null, and it's also the primary key for this table. So this gem, while it's not necessarily a feature for your customer or your end user on your application, it is incredibly valuable for you to have this at a moment's glance inside your code so that you can work much quicker. So this is what we're going to install today. This gem is also extremely popular, as it has almost a million downloads, so we'll 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. This is a gem that doesn't really need to be available in production. So we're just going to leave it in the development group and install it there.

Using the annotate gem is really simple. When you're inside your rails application, all you have to do is type annotate, and this will go through and run the gem against all of the models and tests and other 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 book model inside of our application and see that we have all these comments at the beginning. So we have an id column, a name, description, created_at, upadated_at and so on. And this is immediately available to us as we're working and it makes it of a significantly quicker development time for everything that you're doing. Jus because you can go reference it without having to dive into anything other that the text editor that you're probably already in.

Our user model has been annotated as well, and you can see that these are all the fields that devise provides us. So we have a count of how many times the user has signed in, which is interesting. It's automatically shipped with devise and we may or may not have know that which is really cool, so we know exactly what we're looking at here. Now the other feature that rails provides is annoteate --routes, and if you run this command, it goes through and runs rake routes, and it stores the output inside a comment in your routes file. If we open up our routes file again, you can see that all of the output from rake routes in your terminal is pretty much dumped right here. This is incredibly useful if you're not terribly familiar with your routes, as you get familiar with the syntax for these things, you'll have no problem and not really need this. So I think that's the reason why --routes is not done by default. Because it's sort of just duplicating what you already see here.

Lastly, annotate provides rails integration, so you can rails g annotate:install and this will install a configuration file into your application. Now this is a rake file, and it's a little bit different than a config/initializers file. So the config/initializers just get run every single time you run the rails server. On a rake task however, when you run rake db:migrate for example, that is what is happening with that. So let's open up auto_annotate_models/rake and take a look at it. 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 in as soon as someone runs one of the rake commands that annotate has chosen to integrate with. And the ones that it has chosen to integrate with, are essentially just the rake db:migrate ones. So what happens is, now if you were to go into your application and run a new migration

rails g migration AddNameToUsers name

When we run this, 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'll 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. I know that this is something that I've done manually for a long time where I'll run a migration, and then my comments on annotate will get out of date, and this integration with rake works out extremely well because now I never have to remember that I need to update those, because they should always be up-to-date.