At a recent DCRUG meeting, I was surprised by how many Rubyists, novice and experienced, were unfamiliar with two great documentation tools: annotate_models and RailRoad.
I suspect this is because they relate to the dreaded “d” word: documentation. This is a shame, because these two tools make basic documentation a cinch.
annotate_models
One of the best things about the popular Ruby ORM libraries like ActiveRecord and DataMapper is that you don’t need to spell out the attributes of your models; they are inferred from the database.
Sometimes, though, it is useful to have this information at hand, instead of firing up script/console or your database to answer a simple question like: “Did he call it User.first, User.firstname or User.first_name?”
The annotate_models gem, originally written by Dave Thomas creates a nice comment block at the top of each model, displaying information about the underlying columns/attributes:
# == Schema Information # Schema version: 20090311145521 # # Table name: groups # # id :integer(4) not null, primary key # name :string(255) # description :text # created_at :datetime # updated_at :datetime # status :integer(4) default(1) #
Producing this documentation is as simple as running annotate in your Rails application’s root directory.
Another nice aspect of annotate_models: it will only modify the headers of models that have changed since the last time it was run.
RailRoad
Another useful view of a Rails application, especially a legacy one, is the big picture: i.e., how do all the models (and controllers) fit together? This can be especially daunting when you are following the trail of :belongs_to and :has_and_belongs_to from one file to another.
A free tool, Javier Smaldone’s RailRoad, can tell you all that information at once, by generating a diagram of the models and key information about them, like names, attributes, associations and inheritance relationships.
A minor inconvenience is that the project’s models are outputted in .dot format. This is easily converted into .svg and .png if, like me, you prefer those formats.
Because I do this often, I have added the following alias to my ~/.bashrc and just run rr as needed.
alias rr='railroad -M | dot -Tsvg > doc/models.svg; railroad -M | neato -Tpng > doc/models.png'
If you are happy with .dot files (e.g. you are a GraphViz user), it’s as simple as running railroad -M.
Another cool feature: you can use RailRoad to document your controllers too; just pass it the -C flag instead of -M.
Conclusion
Now, I know this hardly suffices as thorough documentation. However, I also know that I’ve been in web development for a decade and most projects I’ve seen have no documentation at all.
Complete documentation would be great, but it is time-consuming and requires good written communication skills — a tall order for your typical software engineer. Keeping that documentation up-to-date with rapidly-evolving software is even more challenging.
These two tools provide great “bang for the buck”. Check out the repository and run these two commands, and suddenly a legacy Rails application is far less opaque.
I run the commands manually, but you may also consider automating it as part of your build process, or even as a post-hook for rake db:migrate.
Either way, you can trust me on this: if you spend fifteen minutes installing these gems, a few seconds running annotate and rr, you will save hours over the course of your projects.
