[selectors-api] The Naming Debate

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=14_doc67.htm
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.

-- 
Lachlan Hunt
http://lachy.id.au/

Received on Wednesday, 20 June 2007 10:08:47 UTC