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

Re: Selectors API naming

From: William J. Edney <bedney@technicalpursuit.com>
Date: Mon, 18 Dec 2006 20:54:43 -0600
Message-Id: <54712511-02C1-43E3-935F-7DB363A24554@technicalpursuit.com>
Cc: Anne van Kesteren <annevk@opera.com>, Ian Hickson <ian@hixie.ch>, "Web API WG (public)" <public-webapi@w3.org>, Chris Wilson <chris.wilson@microsoft.com>
To: Dave Massy <Dave.Massy@microsoft.com>
All -

I must agree with Dave here. As someone who trains others in Web  
development, the original DOM method names make sense. I can break  
them down this way for my students:


get -> It's gonna return something
Element -> It's gonna return nodes of type Node.ELEMENT_NODE
ById -> It's gonna use 'id' as its criteria.

Unfortunately, both the Mozilla folks and the IE folks have begun to  
deviate from this path for XPath:

<XPathExpression>.evaluate() -> Execute an XPath on Mozilla (this is  
the DOM L3 spec method name, unfortunately)
<node>.selectNodes() / <node>.selectSingleNodes() -> Execute an XPath  
on IE

The problem is, as Dave pointed out, what does 'evaluate',  
'selectNodes', 'selectSingleNode' mean? Those can apply to any one of  
the 3 'selection mechanisms' available (XPath, CSS or DOM) and give  
no clue as to which mechanism is being used.

The W3C has already, for many years, defined these three method names:


Whether folks on this list think that was a mistake is, at this point  
IMHO, quite late in the game. The pattern has been established.

Therefore, getElementsBySelector() is the natural name following the  
well-established pattern.

People talk in terms of 'selectors' in CSS so this at least gives a  
clue as to what selection mechanism is being used (although I guess  
you could use the term 'XPath selector', I've never heard it in  
common use).

If experts choose to encode this as $select(...) or whatever, that's  
their choice. But by the time they're doing that, they're already  
experts. They can 'alias' $select(...) in their head to  
getElementsBySelector() almost subconsciously. I introduce the  
commonly used '$(...)' convenience mechanism to my class *after* I've  
discussed getElementById() and, from then on, they know '$(...)' as  
'a shorthand for getElementById()', not as something in its own right.

Also, at least in ECMAScript, 'match()' is already used for RegExp  

Just thought I'd offer the 'in the trench' perspective.


- Bill

P.S. IMO, the DOM L3 XPath spec that Mozilla implements should be  
changed so that 'evaluate' is 'getNodesByXPath()'.

On Dec 18, 2006, at 4:14 PM, Dave Massy wrote:

> Sorry for the delayed response. We've had a big windstorm up here  
> in the Pacific Northwest that continues to leave many without  
> power, internet or phone.
> We'd really like to see naming to be meaningful for this and all  
> APIs. The goal should be to have a DOM that holds together as one,  
> and therefore the names matter  they need to seem like one  
> intelligently-designed API. Generic names such as select() and match 
> () don't help anyone unless they are for performing generic  
> operations.
> To suggest that names don't matter and "aaaaa" is fine is just  
> wrong in our opinion. We need to have an API set that people can  
> read and understand without having to go to reference material all  
> the time to ask themselves "Hmm. Now what does select() do in this  
> particular situation?".
> Thanks
> -Dave
> -----Original Message-----
> From: Anne van Kesteren [mailto:annevk@opera.com]
> Sent: Friday, December 15, 2006 3:00 AM
> To: Ian Hickson
> Cc: Dave Massy; Web API WG (public)
> Subject: Re: Selectors API naming
> On Fri, 15 Dec 2006 07:58:03 +0100, Ian Hickson <ian@hixie.ch> wrote:
>> My only concern here is that we avoid the mistake that was made with
>> getElementsByTagName and getElementById -- the names should be  
>> easy to
>> type and short. I honestly think that if the one-item method is  
>> shorter
>> than about 6 or 7 characters, then we've made a mistake.
> You mean longer than?
>> So I think "matchSelector" is too long. I think "matchSingle" is too
>> long. I think "select" and "match" are fine.
> I'd love to use "select"...
>> It doesn't matter what the words actually are. I think "aaaaa" is  
>> fine
>> too (though it wouldn't be my first choice). As Maciej points out, we
>> just have to make sure we don't pick a name that makes everyone just
>> alias the
>> method to $ or $$ or something equivalent.
> Yeah, I agree with this.
> -- 
> Anne van Kesteren
> <http://annevankesteren.nl/>
> <http://www.opera.com/>
> !DSPAM:4587133e165412015135145!
Received on Tuesday, 19 December 2006 14:31:42 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:16:22 UTC