Re: Selectors API naming

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:

getElementById()

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:

getElementById()
getElementsByName()
getElementsByTagName()

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  
matching.

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

Cheers,

- 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!