W3C home > Mailing lists > Public > public-webapi@w3.org > December 2006

RE: Selectors API naming

From: Chris Wilson <Chris.Wilson@microsoft.com>
Date: Wed, 20 Dec 2006 09:55:42 -0800
Message-ID: <44FAFFCDE516434D84E6B62121DB6A4404137162@WIN-MSG-21.wingroup.windeploy.ntdev.microsoft.com>
To: Ian Hickson <ian@hixie.ch>
CC: Dave Massy <dave.massy@microsoft.com>, Anne van Kesteren <annevk@opera.com>, "Web API WG (public)" <public-webapi@w3.org>

This is actually in reply to a number of people.


Ian Hickson [mailto:ian@hixie.ch] wrote:
>[Chris Wilson wrote]
>> and that makes the APIs feel like they were designed together.
>
>Sure... But we have to learn from the lessons we were taught by DOM and

>the way that authors are writing code. One of these lessons is that 
>authors will hate typing long method names, to the point where they
will 
>alias one-letter names like $ to their most-used methods, making it 
>completely pointless to have the name be obvious, and making reading
the 
>code far harder than even a short name would have.

I believe some authors do that.  I'm not even going to argue whether
it's a majority or not, though I really doubt that it is.  However, I do
believe that an at least as common way of developing code is that
supported by Visual Studio - AutoComplete.  I've done this myself - I
essentially explore the API through AutoComplete.  From that
perspective, sticking with the pattern established by getElementByID(),
et al, is best - because I start typing "document.getEl" and I get a
dropdown containing:
getElementByID
getElementsByName [if it's an HTML document]
getElementsByTagName
getElementsByTagNameNS
getElementsBySelector

As Martijn said, I believe people will map document.matchAll almost as
often to $$ as document.getElementsBySelector - so I'd much rather stick
with the pattern, and presume that if developers want to map to a()
they'll do it.

>Well, the most obvious method name would be "document.select()". It's 
>clear what it does given the context, and fits in well with the similar

>existing functionality, "document.all". Would "select()" be ok with
you?

Actually, I'd presume "document.select()" would select the document
itself into some context (e.g., it would activate the document, make its
tab the selected one, etc.).  If you have just a verb as the method
name, in my OOP mind I think you're telling that object to do that
action.  That's almost what you're doing here, but not quite - you're
really performing a significant action on the contents of the document,
not the document itself, and the fact that the results are not a live
list (I agree with that decision, btw) would make it even weirder to
have it just be a verb on the document.

Anne van Kesteren [mailto:annevk@opera.com] wrote:
>[Dave Massy wrote:]
>> As I mentioned previously a more complete example of staticNodeList 
>> usage would also be appreciated.
>
>It's not clear to me what you mean with that. It's exactly like the 
>thing getElementsByTagName returns except it's not live. This should 
>be pretty clear from the draft.

I think the points are that 1) the minimalist cases are kinda confusing
(when it's all HTML namespace, e.g., that you don't really need the
namespace param), 2) there's no information on what happens with
undefined HTML namespaces (e.g. no doctype, but I have an XHTML
namespace defined in NSResolver), and 3) an example should probably
explicitly be given that shows removing an element that is in the
staticNodeList from the tree, and that it's still accessible.  I don't
think Dave was saying there's a problem there, just that there's a lot
of ambiguity, and that's how we got into a lot of the DOM
incompatibility messes to begin with.  :)

-C
Received on Wednesday, 20 December 2006 17:56:51 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:18:56 GMT