Re: [selectors-api] The Naming Debate

[Jean-Yves Bitterlich]

Hi As we shared during the Boston F2F, we feel that the 'getX{s}ByZ()' names are better, from a developer's perspective, because they "are very clear and mostly follow established conventions" (as recognized by the spec's author). This clear convention is useful, and not only for DOM APIs. The W3C is sensitive to feedback from implementations and platforms: the 'getX{s}ByZ()' method naming convention is also the preferred convention on the Java platform for getters (setters have a similar structure). We find it unfortunate that past resolutions within the working group are being invalidated (unless of course there are new evidences/information that justify this act) in particular because this behavior leads to rehashing issues instead of moving forward. However, and for the sake of progress, we will go along with the new decision taken in consensus by the WebAPI WG. Jean-Yves -- Senior Staff Engineer, Sun Microsystems GmbH, Sonnenallee 1, 85551 Heimstetten, Germany Geschäftsführer: Marcel Schneider, Wolfgang Engels, Dr. Roland Bömer; Vorsitzender des Aufsichtsrates: Martin Häring Amtsgericht München: HRB 161028, WEEE-Reg.-Nr. DE 20803943; HypoVereinsbank München, Konto 31 625 009, BLZ 700 202 70 -- Lachlan Hunt wrote: Hi,   I've been doing some research into the naming debate, hoping to be able to find a resolution soon.  While I haven't reached a final decision yet, I have been through several hundred emails on the topic and I thought it would be useful to send the research to the list and get any final comments before I make a decision. These are most of the proposed alternatives and a summary of their associated arguments.  Let me know if I missed any significant argument. match()                             matchAll() matchOne()                          matchAll() matchFirst()                        matchAll() matchSingle()                       matchAll() matchSelector()                     matchAllSelectors() matchSelectors()                    matchAllSelectors() * Existing implementation in Dean Edward's Base2 using matchAll() and   matchSingle(). * match() is associated with RegEx.   - Some suggested it was associated with a boolean return value,     but String.match() in JS returns array of matching strings. * "Usually the base method [match()] returns the full result and there    are prefixed/postfixed methods that just return part of it."   -- http://lists.w3.org/Archives/Public/public-webapi/2006Jun/0008.html * "If there is to be another name it should be matchFirst though, not    matchOne, to be clear that it's returning the first match not just    some arbitrarily chose one."   -- http://lists.w3.org/Archives/Public/public-webapi/2006Jun/0011.html * "Having a short name might save us all a few keystrokes but it is less    clear to developers what the call [matchAll] is doing and can create    bigger problems."   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0014.html * "The idea is to make this a common idiom with a convenient name so    people don't have to go to crazy lengths like making $() or $$()    functions to avoid using it."   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0016.html * "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    [longer] than about 6 or 7 characters, then we've made a mistake.   "So I think "matchSelector" is too long. I think "matchSingle" is too    long. I think "select" and "match" are fine."   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0018.html * "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?'".   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0021.html * Many authors don't speak english, so many authors won't understand the   name anyway, but the name should still be clear enough for those that   do. * The name should be intuitive to avoid requiring authors to continually   look them up.   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0026.html * "If this ever implemented interoperably it's probably one of few    things web developers will just remember because they use it so    often."   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0031.html * Using a short name like .match() prevents a future markup language   using a match="" attribute with an associated .match DOM API.   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0098.html select()                            selectAll() selectOne()                         selectAll() selectFirst()                       selectAll() selectSingle()                      selectAll() selectSingleNode()                  selectNodes() selectNode()                        selectNodeList() selectElement()                     selectElementList() selectElement()                     selectAllElements() selectOneElement()                  selectAllElements() * Several people expressed a personal preference for select() and   selectAll(). * Using select*() has the advantage of being somewhat associated with   Selectors. * select() is in conflict with HTMLTextAreaElement.select() and   HTMLInputElement.select(), so it has been immediately ruled out. * selectAll() has potential for confusion with text selection APIs.   There are various APIs that use .selectAll(). Although none of them   seem to be related to the W3C DOM at all, and thus they don't clash,   there are many authors who write scripts for the DOM and also flash   and having document.selectAll() mean significantly different things   in each language would be very confusing. http://msdn2.microsoft.com/en-us/library/system.windows.forms.textboxbase.selectall(VS.71).aspx http://livedocs.adobe.com/dreamweaver/8/apiref/wwhelp/wwhimpl/js/html/wwhelp.htm?href=""> http://livedocs.adobe.com/flash/9.0/main/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Parts&file=00003989.html * selectSingleNode() and selectNodes() are the methods used for XPath   Queries in .NET. * selectNode() and selectNodeList() are too similar to XPath methods,   which may create some confusion. * The .NET XPath methods are precedence for not following the   getElementsBy* convention. choose()                            chooseAll() chooseOne()                         chooseAll() chooseFirst()                       chooseAll() chooseSingle()                      chooseAll() * No known DOM APIs use names beginning with choose*(), so there's no   conflict. * choose*() is a reasonable alternative to select*(). catch()                             catchAll() * Suggested just once, along with the wording:   "I was wondering about catch, catchAll but maybe not a good idea".   -- http://lists.w3.org/Archives/Public/public-webapi/2006Jul/0040.html * catch is a reserved word in many languges for try/catch blocks. get()                               getAll() getOne()                            getAll() getOneElement()                     getAllElements() getElement()                        getElementList() getElementBySelector()              getElementsBySelector() getElementBySelectors()             getElementsBySelectors() getElementByCSSSelector()           getElementsByCSSSelector() getElementBySelector()              getElementListBySelector() getElementBySelectors()             getElementListBySelectors() * Many argued that the name should be in line with conventions for   existing DOM APIs like getElementsBy*() * The getElement*/getElements* variants look too similar to each other,   which makes editing more difficult than it should be. * getElementList* attempts to address the readability issue, but is not   consistent with existing method names. * getElementBySelectors/getElementListBySelectors was the resolution   in this WG meeting http://www.w3.org/2007/01/25-webapi-minutes.html * The plural form *Selectors may be technically more accurate, but it   seems unintuitive for authors who won't understand the difference and   has no benefit over the singular form. * "The problem is that it requires _javascript_ programmers to type 22    characters before encountering characters that uniquely identify it,    and 19 characters before it's clear that the method will return a    NodeList."   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0051.html * Authors generally don't like long method names and shouldn't be forced   to alias the names, like the many using $() for getElementById(). * Existing getElementsBy*() methods return live node lists, whereas   this returns a static node list.   -- http://lists.w3.org/Archives/Public/public-webapi/2006Dec/0088.html * The slight practical difference between live and static node lists   shouldn't really affect the naming. * These methods provide a superset of the functionaliry given by the   existing getElementsBy* methods, which justifies having a name like   get() or getElement().   -- http://lists.w3.org/Archives/Public/public-webapi/2007Jan/0031.html getElementByGroupOfSelectors()      getElementsByGroupOfSelectors() getElementByGroupOfSelectors()      getElementListByGroupOfSelectors() * Although these names are technically more accurate, sacrificing ease   of typing for this would be unnacceptable. nodeBySelector()                    nodeListBySelector() * These just shorten the name by removing the get prefix, which breaks   the convention. getNode()                           getNodes() getNode()                           getAllNodes() getNodeBySelector()                 getNodeListBySelector() getNodeByExpr()                     getNodeListByExpr() getBySelector()                     getBySelectorAll() * These name leave open the possibility that selectors may one day match   non-element nodes in the future without the names suddenly becoming   technically incorrect. * Using Expr instead of Selector doesn't make much sense, since it's not   an _expression_. getElementBySelector()              getNodeListBySelector() * This name is technically more accurate because the first returns a   single element and the second returns a static node list, but the   inconsistency would be confusing for authors. css()                               cssAll() cssQuery()                          cssQueryAll() matchCSS()                          matchCSSAll() * Selectors aren't just for CSS, as this API clearly demonstrates.   (also applies to the *ByCSSSelector variants above) * People commonly associate selectors with CSS anyway, but I don't think   we should encourage this increasingly confusing misconception. * "I have a suspicion that ".css*()" would *really* confuse people into    thinking it's a way of setting CSS style properties, or getting    elements by classname, or just about anything other than a generic    selector language."   -- http://lists.w3.org/Archives/Public/public-webapi/2007Jan/0044.html * "1) css is not a verb 2) this sounds like it would return style    declarations, not elements."   -- http://lists.w3.org/Archives/Public/public-webapi/2007Jan/0046.html * cssQuery was previously implemented and used in a _javascript_ library. -- Jean-Yves Bitterlich Senior Staff Engineer Sun Microsystems GmbH Sonnenallee 1, 85551 Heimstetten, Germany Mobile: +49-172-8187243 Phone: +49-89-46008-1097 (x61097) Fax: +49-89-46008-2978 (x62978) Email: [EMAIL PROTECTED] Amtsgericht München: HRB 161028 Geschäftsführer: Marcel Schneider, Wolfgang Engels, Dr. Roland Bömer Vorsitzender des Aufsichtsrates: Martin Häring WEEE-Reg.-Nr. DE 20803943 HypoVereinsbank München, Konto 31 625 009, BLZ 700 202 70