Language &Philosophy &Programming Languages &Software 12 Nov 2007 11:35 am

Document the Difficult Stuff, not the Easy: Rails Tutorials

I found Rails Tutorials pretty handy. They are short and sweet focusing on only one particularly problem per tutorial. I also found some good discussion in the comments of each tutorial. With their help, I finally got my head around how to deal with creating complex relationships of objects and dependent objects so that they are put in the database atomically, and so that they are available for error correction on the form if there were validation errors.

A big part of the problem I was having is that there are a million tutorials on the simple stuff in Rails and ActiveRecord, but very few on doing real work. There are many features of the Rails framework that I have just happened across accidentally, or that I had to scour the net and books looking for examples.

The one particular bug, err… feature, that has been haunting me is how to create an object that has a complex join model, and have all the other objects in that model get created automatically.

It is obvious enough for me to do it by hand. For example, creating a Registration for multiple People for multiple Courses, with other related information like Payment choices and related details to the Registration. When I get back a form, I could pick out each parameter set in my form fields. I could then create each object, Registration, People objects, Payment details, etc.. and then set them on the Registration object.

@registration =[:registration])
new_payment =[:payment])
@registration.payment = new_payment;
@registration.people = params[:people].collect { |[], person| }

But rails should be able to do all this automatically since I already specified the relationships in the model objects. Well, turns out it can. You can use the build method on the model objects.

params[:people].each {|person| }

However, this doesn’t work for has_one or belongs_to objects, for those you have to call


Notice that this seems to be some sort of method_missing magic. I haven’t hunted down where this gets handled, but more troubling to me is that I never knew it even existed. I am glad I found it of course, but it is the first time in Ruby I have had the feeling that dynamic features could be bad.

I know the horror stories of dynamic languages and the claims for static typing and so on, but by and large I have not had this problem with Ruby, and I have probably written about 15-20kloc of Ruby now. Not a great amount, but not a trivial amount either given the expressiveness of the language.

Maybe I should have learned Rails by looking at the test suites. Perhaps within that code I would’ve found examples of build_x and that would have clued me in. I don’t know if those tests exist, but still I think that tutorials can be more efficient communication than test suites.

Of course that depends on what tutorials get written. My Request:

When writing tutorials for programmers, just write the tutorials for the hard stuff.

This should be the priority. Assume that programmers can figure out the obvious stuff, and spend your time on explaining the hard, hidden parts of the framework.

Subscribe to the comments through RSS Feed

Leave a Reply