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.