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