This project is archived and is in readonly mode.

#1328 ✓wontfix
Carlos Paramio

One-to-one Association example at docs is confused

Reported by Carlos Paramio | November 4th, 2008 @ 07:12 PM | in 2.x

At the ActiveRecord::Associations::ClassMethods module, in the documentation about "Cardinality and associations", the One-to-one example is confused. The example refers to an office that belongs to one employer (?), and an employer that has one office, leaving the foreign key on the Office model pointing to the employee_id. I think that the reversed example is much more natural and nearer to the reality: An employee belongs to an office, and the office has one employee, creating the office_id foreign key at the Employee model. This example also leaves the posibility for the database structure to grow to a multiple-employee office design, just by changing the has_one macro by has_many, without touching the database.

I've attached a patch against the master branch that modifies the example.

Comments and changes to this ticket

  • Carlos Paramio

    Carlos Paramio November 4th, 2008 @ 07:13 PM

    s/confused/confusing/ ;-)

  • Carlos Paramio

    Carlos Paramio November 4th, 2008 @ 07:26 PM

    • Tag changed from activerecord, belongs_to, doc, documentation, has_one to activerecord, belongs_to, doc, documentation, has_one, patch

    I used "git diff" to create the patch, but checking the documentation, it seems that the preferred format is the output of "git format-patch", so I've included the new patch file that substitutes the first one, with extension ".diff" as it appears at the contributions guide. My apologize for any inconvenience.

  • Josh Susser

    Josh Susser November 16th, 2008 @ 02:07 PM


    has_one vs belongs_to is always going to be a matter of perspective. There's no point in making this change because the new example will be just as confusing to just as many people as the current one is. And what if an employee works in multiple offices? The only "real world" mapping that works is many-to-many. Can we leave this contrived example alone?

    If this mapping needs to be discussed further, it should be about how the location of the foreign key impacts database performance and application architecture. But that's beyond the scope of this section.

  • DHH

    DHH November 16th, 2008 @ 02:48 PM

    • State changed from “new” to “wontfix”

    I agree with Josh. But don't let that stop you from keeping at improving Rails documentation. Thanks for being interested in helping.

  • CancelProfileIsBroken

    CancelProfileIsBroken November 16th, 2008 @ 03:03 PM

    In addition, we have for more details on associations. Feel free to submit a patch in the docrails project if you think the coverage there can be improved.

  • Carlos Paramio

    Carlos Paramio November 16th, 2008 @ 03:57 PM

    Good point. I just saw more natural the reversed case (maybe because it could be more common), but it's true that the example won't be like "real world" in any case. Thanks for your comments!

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile »

<h2 style="font-size: 14px">Tickets have moved to Github</h2>

The new ticket tracker is available at <a href=""></a>