How do you describe the fields in your database?

[MarkBennett]

I'm working on an application where the fields in our model have very
specific meanings and affect payments made to our users. Because of
this understanding the purpose and meaning of each field is important.

I've been looking for the best way to describe the model fields, and
would ideally like to leave comments in the db/schema.rb, however this
if rebuild after I run each migration. What is the best way to
document fields and to share their purpose with the team? I can't
find a comment or description field to use the migration code, and
describing each field in the model file itself doesn't seem very DRY.

Thanks!

[Bodaniel Jeanes]

Why do you find describing the fields in the model unDRY? If it were me, that's exactly where I'd put them as this is where developers will interact with those fields the most.

Another idea might be to patch migrations to use the field comment feature of some DBs like MySQL. However without actually checking that, it's not really helpful as most developers won't regularly check the schema.rb or the raw database to see those values.

Ultimately if the purpose is for documentation, it should be somewhere that developers will expect to find documentation: the README, the doc/ directory, or in comments in the code (such as in the model that it is relevant to).

Bo

[James Healy]

Bodaniel Jeanes wrote:
> Ultimately if the purpose is for documentation, it should be somewhere that
> developers will expect to find documentation: the README, the doc/
> directory, or in comments in the code (such as in the model that it is
> relevant to).

The only problem with that is that a developer may create a migration
and forget to update the field descriptions in the model. Out of date
and wrong comments are the worst.

I like the idea of patching migrations to use the field comment in the
database. Then plugins like annotate models could pull the comment and
write it to the model file for easy access.

-- James Healy <ji...@deefa.com> Wed, 04 Nov 2009 12:11:46 +1100

[MarkBennett]

Right now I look in the db/schema.rb to see the list of fields
associated with a model and assume that is where most other people
look for these fields, which is why I wanted to put the descriptions
there. My thinking is that repeating this list of fields again in the
code in app/models is unDRY because you've now got to maintain the
same list of fields in both places.

When you say most developers don't regularly check the schema.rb, how
do you know what a model's fields are without doing this? I agree
that most developers, myself included, usually go to the app/model
file first when coding. This is one of the few things I find annoying
about ActiveRecord because I often have to have the db/schema.rb and
app/models file open at the same time. If there is a good way to add
these comments to the model I'd rather describe them there so that
they also appear in the rdoc. An example would probably help the
most.

Thanks for your quick reply!

On Nov 4, 12:05 pm, Bodaniel Jeanes <m...@bjeanes.com> wrote:
> Why do you find describing the fields in the model unDRY? If it were me,
> that's exactly where I'd put them as this is where developers will interact
> with those fields the most.
>
> Another idea might be to patch migrations to use the field comment feature
> of some DBs like MySQL. However without actually checking that, it's not
> really helpful as most developers won't regularly check the schema.rb or the
> raw database to see those values.
>
> Ultimately if the purpose is for documentation, it should be somewhere that
> developers will expect to find documentation: the README, the doc/
> directory, or in comments in the code (such as in the model that it is
> relevant to).
>
> Bo
>

[Bodaniel Jeanes]

The only problem with that is that a developer may create a migration

and forget to update the field descriptions in the model. Out of date
and wrong comments are the worst.

Good point. Hard to find documentation still sucks though 

 

I like the idea of patching migrations to use the field comment in the
database. Then plugins like annotate models could pull the comment and
write it to the model file for easy access.

If the process of pulling out the value of these fields and displaying them somewhere is automatic this scenario would become very useful.

[Bodaniel Jeanes]

On Wed, Nov 4, 2009 at 11:19 AM, MarkBennett <mark.f....@gmail.com> wrote:

Right now I look in the db/schema.rb to see the list of fields
associated with a model and assume that is where most other people
look for these fields, which is why I wanted to put the descriptions
there.  My thinking is that repeating this list of fields again in the
code in app/models is unDRY because you've now got to maintain the
same list of fields in both places.

Sure. My point should have been more that you *don't* maintain the schema.rb file -- the migrations do.  

When you say most developers don't regularly check the schema.rb, how
do you know what a model's fields are without doing this?

I usually just type in the class name in my (already open) console window:

>> Account

=> Account<id: integer, created_at: datetime, updated_at: datetime, full_domain: string, deleted_at: datetime, owner_id: integer>

[Josh Price]

Does anyone still use the annotate models plugin?

http://agilewebdevelopment.com/plugins/annotate_models

It takes your schema and put it as a comment block at the top of your model classes. Combined with migration-based comments this might work for you.

When I used this a while back I found keeping it up to date manually mildly annoying, but if your schema isn't going to change much then it might be a good solution.

Josh

[MarkBennett]

Hey Josh:

I think annotate_models is exactly what I'm looking for. Giving it a
go can't hurt. :)

Cheers!

-Mark

[Dave Bolton]

> Does anyone still use the annotate models plugin?

Yeah, loved it (taking noted mild annoyances into account). There's
been some small modifications by me and others too to make it a bit
more usable:
http://github.com/lightningdb/annotate_models

Cheers,
Dave

[Nathan de Vries]

On 04/11/2009, at 12:28 PM, Josh Price wrote:
> Does anyone still use the annotate models plugin?

I used to use a customised version of "rake model_annotations:update",
which allowed you to place a comment next to each field that wouldn't
get blown away if you re-ran the task. I then had a "rake
model_annotations:missing" task which listed all models/fields with
missing annotations. Useful in team environments, and if you can't
express enough information in the name of the actual fields.

Cheers,

Nathan

[James Healy]

Josh Price wrote:
> Does anyone still use the annotate models plugin?
>
> http://agilewebdevelopment.com/plugins/annotate_models
>
> It takes your schema and put it as a comment block at the top of your model
> classes. Combined with migration-based comments this might work for you.
>
> When I used this a while back I found keeping it up to date manually mildly
> annoying, but if your schema isn't going to change much then it might be a
> good solution.

I use it and find it handy for keeping a list of DB fields within easy
reach when working on a model. I don't think it currently extracts
fields comments from the DB however.

One minor irritation is that it doesn't interact nicely with files that
have a ruby 1.9 encoding statement (# coding: utf-8 and friends) at the
top of the file.

-- James Healy <ji...@deefa.com> Wed, 04 Nov 2009 12:37:36 +1100

[Josh Price]

On Wed, Nov 4, 2009 at 12:38 PM, James Healy <ji...@deefa.com> wrote:

Josh Price wrote:
> Does anyone still use the annotate models plugin?
>
> http://agilewebdevelopment.com/plugins/annotate_models
>
> It takes your schema and put it as a comment block at the top of your model
> classes. Combined with migration-based comments this might work for you.
>
> When I used this a while back I found keeping it up to date manually mildly
> annoying, but if your schema isn't going to change much then it might be a
> good solution.

I use it and find it handy for keeping a list of DB fields within easy
reach when working on a model. I don't think it currently extracts
fields comments from the DB however.
 

Yes field comment extraction would need to be added if someone hasn't already done this.

Josh

[Dan Cheail]

Does anyone still use the annotate models plugin?

Yeah, loved it (taking noted mild annoyances into account). There's
been some small modifications by me and others too to make it a bit
more usable:
http://github.com/lightningdb/annotate_models

There's another fork of it, which has been re-packaged as a gem:

http://github.com/ctran/annotate_models

- Dan

[Anthony Richardson]

On Wed, Nov 4, 2009 at 11:49 AM, MarkBennett <mark.f....@gmail.com> wrote:
> When you say most developers don't regularly check the schema.rb, how
> do you know what a model's fields are without doing this?

I have my SQL gui application open all the time where I can look at
everything as well as query the db. I never looked at schema.rb

Cheers,

Anthony

[Daniel N]

I use DataMapper where possible.  Everything is declared in the class.  Just like real ruby! 

[Ryan Bigg]

I store the database schema in my mind and know what every column's purpose is.

2009/11/5 Daniel N <has...@gmail.com>

--
Ryan Bigg

[Gareth Townsend]

On 05/11/2009, at 10:04 AM, Ryan Bigg wrote:

> I store the database schema in my mind and know what every column's
> purpose is.

So you've never working on anything bigger than a blogging engine then?

Cheers,
Gareth Townsend
http://www.garethtownsend.info
http://www.melbournecocoaheads.com

[Ryan Bigg]

From: http://www.google.com.au/search?q=define%3A+joke

Definitions of joke on the Web:

• a humorous anecdote or remark intended to provoke laughter; "he told a very funny joke"; "he knows a million gags"; "thanks for the laugh"; "he ...
• jest: activity characterized by good humor
• tell a joke; speak humorously; "He often jokes even when he appears serious"
• antic: a ludicrous or grotesque act done for fun and amusement
• act in a funny or teasing way
• a triviality not to be taken seriously; "I regarded his campaign for mayor as a joke"  

2009/11/5 Gareth Townsend <gareth....@me.com>

--
Ryan Bigg

[Ian White]

This thread makes me so wish I was going to railscamp :(

[Ryan Bigg]

However this is most likely the case for rboard.

2009/11/5 Ryan Bigg <radarl...@gmail.com>

--
Ryan Bigg

[Daniel N]

You're not coming :'(  We'll make sure there's plenty of alcohol consumed on your behalf!

[Lachie]

a triviality not to be taken seriously; "I regarded his contribution
to the thread as a joke"

:lachie
http://plus2.com.au
http://smartbomb.com.au
http://www.flickr.com/photos/lachie/

[Ian White]

MEXICAN

[Gareth Townsend]

Don't worry Ian, we'll hook up an internet connection and iChat over video, just so you can play along :)

[Brian Chiha]

For what its worth,

RubyMine IDE has a 'Rails' view which along with class methods it will show model database fields. It also can generate a Model dependency diagram showing model fields and relationships.. kind of like using railroad and dot

http://www.jetbrains.com/ruby/features/rails_editor.html

Brian.

This email is intended for the use of the individual or entity it is addressed to and may contain information that is confidential, legally privileged, commercially sensitive, or protected by copyright. If it contains financial product advice, the advice is of a general nature and you will need to determine how appropriate it is for you.

If you are not the intended recipient you must not disclose, disseminate, distribute or copy information contained in it. If you have received this e-mail in error, please notify the sender immediately and destroy the original message. While this mail and any attachments have been scanned for common computer viruses and found to be virus free, we recommend that you perform your own virus checks before opening any attachments.

______________________________________________________________________________

This email has been scrubbed for your protection by SMX.
For more information visit http://smx.co.nz
______________________________________________________________________________

[Enrico Teotti]

you said the fields have: "very specific meanings and affect payments
made to our users"

wouldn't it be good to document them using some Model specs so that it
makes clear what the field does, and how it affects the payment
system?
Of course annotate_model will always be there, I think it even
annotate your specs btw...
ceo