Consolidating the Helpers API

[Clemens]

Hi there,

Since I've joined the effort to improve Rails' documentation with
Pratik's docrails project, I've spent a lot of time digging through
Rails' source code - especially the Helpers. I realized that in some
parts the API isn't really intuitive because it's inconsistent.

I've already created a ticket at Lighthouse (http://
rails.lighthouseapp.com/projects/8994/tickets/606-inconsistent-
functionality-in-date_helper-rb) but so far no one seems to have
recognized it so I thought I'd discuss it here.

I've got two important points (until I can think of more ;)) I'd like
to put up for discussion:

The first is already indicated in the existing Lighthouse ticket: A
single helper should - if at all possible - have consistent options.
Consider the date helper: The non-object-related helpers (such as
select_date) allow to modify the separators while the object-related
ones (such as date_select) don't.

Secondly, I'd love if all (or at least wherever it's possible) helpers
ditch fixed parameters and replace it with an options hash (or two).
Again, this is about consistency and being intuitive. Look at the
number helper, for example: number_to_currency, number_to_percentage
and number_to_phone each take the number and an options hash.
number_to_human_size, number_with_delimiter and number_with_precision
take the number and given arguments in a fixed order. That's
inconsistent. You can't even argue that it's got to do with the number
or type of parameters because both, number_to_percentage and
number_with_delimiter, take *exactly* the same options (delimiter and
separator). I'd really like it if all helpers would have a similar and
consistent interface: They should first take any required parameter
(e.g. the number for the number helper) and after that use one or two
options hashes to modify their behavior.

The way I see it, we could even make a smooth transition. We could
splat all configuration parameters (i.e. all non-required parameters)
and use methods like extract_options! in combination with args.size to
evaluate whether the old or new API style was used.

I quickly put together a small example that refactors the
number_with_delimiter method to illustrate my point: http://pastie.org/235309

Maybe it would even be a good idea to deprecate the old stuff and
ditch it for the next major release - but then again, who am I to
decide that stuff? ;-)

I'd love to hear what you guys from the core team and other people
think about it before getting down to work. The NumberHelper is, I
think, would be fairly easy to refactor but more complex stuff (like,
for example, the DateHelper) will be a challenge.

Best,
- Clemens

[Clemens]

If anyone's interested, I've forked Rails and started work on it here:
http://github.com/clemens/rails
NumberHelper is already updated, including tests and docs (although I
might rework the docs to make them more consistent).