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

Re: Selectors API naming

From: Doug Schepers <doug@schepers.cc>
Date: Thu, 21 Dec 2006 17:56:14 -0500
Message-ID: <458B110E.8010007@schepers.cc>
To: Anne van Kesteren <annevk@opera.com>
Cc: "Web API WG (public)" <public-webapi@w3.org>

Hi, Anne-

Anne van Kesteren wrote:
> 
> Currently the following methods exist:
> 
>  * document.getElementsByTagName()
>  * document.getElementsByName() (HTML only)
>  * document.getElementById()
> 
> The following method is proposed by the WHATWG:
> 
>  * document.getElementsByClassName()

I'd really like to use that.  It's very useful.


> These four methods all return a _live_ NodeList meaning that when 
> something in the DOM is changed the variable that holds the NodeList is 
> changed accordingly, if needed.

document.getElementById() returns an element, not a nodeList [0].  It 
doesn't seem that it's live.


> If we would name the new pair as follows:
> 
>  * document.getElementBySelector()
>  * document.getElementsBySelector()
> 
> They would not be consistent with the previous four mentioned methods as 
> they would not return a live NodeList but a StaticNodeList. Which means 
> that when an attribute value changes the StaticNodeList does not need to 
> be updated for a group of selectors that uses an attribute selector 
> somewhere.

document.getElementBySelector() should return an element, not a nodeList 
(live or static); it's like document.getElementById().

In practical terms, regardless of whether the list is live or not, the 
same accessor, looping, and assignation mechanisms would still work for 
both.

Personally, the liveness has always struck me as more of a bug than a 
feature.  Thus my code always strives to avoid the negative aspects of a 
live nodeList, and I suspect that others code the same way.  I don't see 
a negative impact in my current methodology of the list being static.


> These names would also be slightly confusing as they would not take a 
> selector but rather a group of selectors. I suppose the group in favor 
> of these methods find that acceptable. I wonder if they find the 
> inconsistency with the other DOM methods to be acceptable as well. 
> Personally I don't really like that.

Again, I don't care if the names are different, to reflect this (minor) 
difference.  For example, I'd be happy with:

  * document.getNodeBySelector()
  * document.getNodelistBySelector()

or something similar.

> It seems that libraries find there's a need to provide shortcuts for the 
> several of the above mentioned methods (notably document.getElementById 
> and document.getElementsByTagName). Several authors have argued that 
> they don't see a need for such a thing but no "evidence" has been 
> provided. No evidence to the contrary either, though.

As has been stated, there may be reasons for using method aliases that 
are unrelated to the length of the method.  Even if that is one of the 
reasons, I don't think that it's a compelling argument, certainly not 
proof of "failure".  It might be better not to assume that these 
alias-happy authors are doing it for the reasons you maintain.

My colleagues who do use aliases, for example, do so to abstract out the 
  framework that they use (dojo, as it happens) in order to add 
functionality and to future-proof their own code against underlying 
changes, not merely to make shorter names.  BTW, they do hundreds and 
thousands of lines of code, and they prefer the longer names, as well.

Consider that the aliasing may be done because the library wants to 
achieve cross-platform compatibility, and they use the shorter name 
because the more descriptive name is already taken.  Have we solicited


> I'm personally not really convinced by the autocomplete argument. I 
> don't really think it's good language design to assume there's such a 
> thing.

I don't use autocomplete, and I don't mind the slightly longer names.


> I'm still leaning towards not changing the draft with regard to naming 
> for reasons mentioned above, but if someone can tackle the problems 
> mentioned above I'm willing to reconsider.

I don't see the problem you're talking about.

The clear majority of individuals and arguments in this thread favor 
longer descriptive naming conventions (including others from your own 
company).  Further, I haven't seen counterarguments against most of the 
points in favor of this stance.  No offense, but your conviction does 
sound more ideological than logical.


[0] http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-getElBId

Regards-
-Doug
Received on Thursday, 21 December 2006 22:56:28 GMT

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