On Mon, Feb 20, 2006 at 01:59:40PM -0800, Joshua S. wrote:
documentation for under what circumstances find() returns a single
object vs a list, when it raises an exception, etc.
Can anyone shed some light on this design decision? Any chance of
getting those deprecated APIs supported again?
One of the lessons of API design that has emerged from the development
Rails is that when you need to do something in several slightly
ways, write a single method and parameterize it with an options hash
than write several similar methods.
So rather than the positional parameters that you had to pass to
find_all, we now have the single find with the symbol and option hash
you talk about above. Similarly, render_file, render_template,
render_partial, render_collection_of_partials, (etc…), turn into a
render method, which dispatches to the desired functionality depending
options hash passed to it. This approach is, essentially, “multiple
(http://en.wikipedia.org/wiki/Multiple_dispatch), which is built into,
example, the Common Lisp Object System
What’s good about this API?
Fewer methods to remember
Which also means, fewer method signatures to remember
You can add options thereby increasing the method’s utility without
changing the method signature, preserving backwards compatability
Encourages elegant usage
When you have only one method as your point of entry, you also only
one method signature. You can build a hash dynamically and pass it
your method. You don’t have to contruct the name of and dynamically
the desired method while conditionally determining the appropriate
positional parameters to pass in. Sometimes the latter case is easy
but when it isn’t, it gets really messy, really fast.
With the implementation details increasingly hidden inside the
framework, it is
the framework’s responsibility, rather than your’s, to figure out
make a single method do the job of, in the case of render, 10
These multiple dispatch style methods provide a lot of functionality
their option hash, yet the single point of entry with just the single
stricking a balance between a “Humane Interface”
(http://martinfowler.com/bliki/HumaneInterface.html) and a “Minimal
That is of course not the whole picture. But it’s the start of an
The old methods have indeed been officially deprecated and have been so
probably about over a year now. They could disappear any day now. I
imagine them becoming undeprecated.
You indicated that the find_all and find_first were more natural to you
you said it would simplify things to have them split up. Is the relative
“naturalness” your primary beef with the single find method? It is my
experience that from both the framework implementation side and the
API side, the single find method is both more natural and simpler.