- From: Jean-Yves Bitterlich <Jean-Yves.Bitterlich@Sun.COM>
- Date: Wed, 27 Jun 2007 20:13:55 +0200
- To: public-webapi <public-webapi@w3.org>
- Cc: Lachlan Hunt <lachlan.hunt@lachy.id.au>
- Message-id: <4682A8E3.5000500@sun.com>
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=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.
>
--
<http://www.sun.com/> *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: / Jean-Yves.Bitterlich@Sun.COM
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
Received on Wednesday, 27 June 2007 18:14:13 UTC