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