[meta] Consistency In API
From ptwobrussell:
As I'm writing this book on Dojo, I'm looking at the totality of the toolkit from an API-centric point of view (especially Base) and am noticing (fairly minor) inconsistencies that we may want to consider "fixing". For example:
- In html.js, most functions from this family accept either a string id or a dom node as a first param, but a few (like hasClass, addClass, etc.) accept only a dom node and fail if you accidentally (because you're generalizing your knowledge from other functions) pass in an id value. So there's the size (extra dojo.byId call) vs consistency vs performance vs breakage considerations in dealing with fixing something like this.
- In other places, params to families of functions are named different things, so it would be nice to name params consistently across the board so that the "family" relationship might be even more apparent, so that your doc tools produce a nice consistent API, etc. (things like obj vs thisObject vs o as param names, for example.)
In either of these cases, I'd be happy to generate the patches since I'm _almost_ generating them anyway as I sift through all of these things in my writing efforts. However, in that first issue especially, it seems as though there would need to be a little pow-wow to get to some final decision.
Change History (15)
Milestone: |
→ 1.0
|
Owner: |
changed from anonymous to alex
|
Milestone: |
1.0 →
1.1
|
Status: |
new →
assigned
|
Summary: |
Consistency In API →
[meta] Consistency In API
|
Description: |
modified (diff)
|
Milestone: |
1.2 →
future
|
Owner: |
changed from alex to dylan
|
Status: |
assigned →
new
|
Resolution: |
→ fixed
|
Status: |
new →
closed
|
Names
Well, I think we'd appreciate patches for standardizing naming of positional parameters and types (like "DomNode?" vs. "HtmlElement?"), although I remember endless debates about abbreviations vs. spelled out names (spelled out names sound good until you get tired of typing "replaceVariables" instead of "replaceVars"). As for named parameters like in
etc. changing those would mean an API change which would inconvenience our current users, so that's got pros and cons.
Dual ID vs Node arguments
This was also the topic of much debate, as it trades off convenience for efficiency and code size. I think the conclusion was to only make really common functions take an id or a node, but to make uncommon functions just take a node. So it's by design, and I'd hate to beat that dead horse again.