Annotate Models Plugin

Rails model files contain no information on the tables they represent. This is a good thing in general, because it reduces duplication—add a column to a table, and there’s no configuration to update in the model.

However, when you’re writing code, it’s sometimes nice to be able to see just what attributes a model has.

Enter annotate models, a really trivial Rails plugin I hacked up in the plane back from the first No Fluff of the year. The plugin adds a comment block to the top of each model file, documenting the schema. If you update the schema, run it again and it updates the comment.

  # Schema as of Mon Feb 27 00:55:58 CST 2006 (schema version 7)
  #
  #  id                  :integer(11)   not null
  #  name                :string(255)
  #  description         :text
  #  image_location      :string(255)
  #  price               :float         default(0.0)
  #  available_at        :datetime
  #

  class Product < ActiveRecord::Base

    validates_presence_of :name, :description
    . . .

Install using:

  > script/plugin install http://repo.pragprog.com/svn/Public/plugins/annotate_models

and run with:

  > rake annotate_models

It only handles models directly under app/models. And, as it’s new, you’d be advised to back up your model files before running it.

Comments

[Cédric Hernalsteens]

Thanks Dave !

[MartOn]

The svn is not working properly. I'm not able to check out the plugin. Has the repository moved?

[dailer]

In your implementation I found the following regex worked better for me:

content.sub!(/^# #{PREFIX}.*\n(#.*\n)*/, '')

otherwise it required two empty lines after the last comment.

[dailer]

I also found it was adding an extra space after the inserted comments on each run, so at the end of get_schema_info,

info << "#\n"

instead of

info << "#\n\n"

[Gregory Tomei]

nice one Dave, thanks! I find this useful

[Tim Harper]

This is an awesome plugin and I use it on every project.

I have 2 things I always change in it:

First, I take the schema version number out of the annotation, so I don't get a brand new commit for every model everytime I run a migration.

Second, I change the write mode to be "wb" instead of "w" - This ensures that the files are written with unix line-endings, regardless of the platform

Thanks Dave!

[Glenn Rempe]

Hi,

Cool plugin.

I use Git, and I have it set to check for trailing spaces in my code before commit so I am a bit anal about trailing spaces :-)

I changed line 45 to strip trailing spaces.

from :

info << sprintf("# %-#{max_size}.#{max_size}s:%-15.15s %s\n", col.name, col_type, attrs.join(", "))

to :

info << sprintf("# %-#{max_size}.#{max_size}s:%-15.15s %s\n", col.name, col_type, attrs.join(", ")).gsub(/\s+$/, $/)

Now it works the same, just missing the empty trailing spaces. :-)

[Chris]

doesn't work with set_table_name

[Trdunsworth]

I'm having a problem with doing
script/plugin install http://repo.pragprog.com/svn/Public/plugins/annotate_models

I'm getting a Plugin not found return when I try to run this. I'm doing it from Windows (don't gasp please...) and from Ruby 1.8.7 Rails 2.3.5

any suggestions as to why it's not working now and what to do with it?

Thanks,