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.
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
On Wed, Nov 4, 2009 at 10:56 AM, MarkBennett <mark.f.benn...@gmail.com>wrote:
> 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.
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
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
> On Wed, Nov 4, 2009 at 10:56 AM, MarkBennett <mark.f.benn...@gmail.com>wrote:
> > 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.
> 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.
On Wed, Nov 4, 2009 at 11:19 AM, MarkBennett <mark.f.benn...@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:
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.
On Wed, Nov 4, 2009 at 12:20 PM, Bodaniel Jeanes <m...@bjeanes.com> wrote:
> 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.
> 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
> On Wed, Nov 4, 2009 at 12:20 PM, Bodaniel Jeanes <m...@bjeanes.com> wrote:
> > 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.
> 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
> 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.
> 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.
> 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
> > 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.
>> 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:
On Wed, Nov 4, 2009 at 11:49 AM, MarkBennett <mark.f.benn...@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
> On Wed, Nov 4, 2009 at 11:49 AM, MarkBennett <mark.f.benn...@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
I use DataMapper where possible. Everything is declared in the class. Just like real ruby!
> On Thu, Nov 5, 2009 at 9:46 AM, Anthony Richardson <
> goo...@anthonyrichardson.com> wrote:
>> On Wed, Nov 4, 2009 at 11:49 AM, MarkBennett <mark.f.benn...@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
> I use DataMapper where possible. Everything is declared in the class.
> Just like real ruby!
- 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"
> 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"
> - 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"
> - 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"
> 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"
>> 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"
>>> 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"
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
-----Original Message-----
From: rails-oceania@googlegroups.com [mailto:rails-oceania@googlegroups.com] On Behalf Of Anthony Richardson
Sent: Thursday, 5 November 2009 9:46 AM
To: rails-oceania@googlegroups.com
Subject: [rails-oceania] Re: How do you describe the fields in your database?
On Wed, Nov 4, 2009 at 11:49 AM, MarkBennett <mark.f.benn...@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
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 ___________________________________________________________________________ ___
|
