Wednesday, August 29th, 2007

Selectors API Method Names: selectElement() and selectAllElements()

Category: JavaScript, Standards

Naming is hard. Lachlan Hunt took the naming of methods in the new W3C Selectors API very seriously and after choosing selectElement() and selectAllElements() he wrote a bit of a tomb describing how he came up with the names:

Rationale for Naming Principles

A short name is important for several reasons. Since these methods are
designed, and behave, as a superset of the existing getElementsBy*
methods, it is likely that their use will significantly replace the use
of previous methods.

Based on evidence from many widely used JS libraries, and other
feedback, we know that authors generally prefer shorter names over
longer names. This is particularly true for methods that will be
frequently used.

Not only does a shorter name reduce the amount of typing, it can help to
improve the readability of the source code, which in turn makes code
easier to maintain. Given these reasons, I have concluded that, within
reason, short names are a fundamental requirement that must be adhered to.

Ideally, the chosen method names would be relatively clear and
unambiguous with regards to their purpose, usage and return value.
However, this must be put into perspective; the names do not need to
describe these aspects perfectly.

I am glad it isn’t getElementsByGroupOfSelectors.

NOTE: What is the Selectors API?

Selectors, which are widely used in CSS, are patterns that match against elements in a tree structure. The Selectors API specification defines methods for retrieving Element nodes from the DOM by matching against a group of selectors. It is often desirable to perform DOM operations on a specific set of elements in a document. These methods simplify the process of aquiring specific elements, especially compared with the more verbose techniques defined and used in the past.

UPDATE: Dean has actually implemented the Selectors API in his base2.DOM library and has taken out his getElementsByClassName implementation (as he can’t return a live node list). All you have to do is s/document.getElementsByClassName(“my-class”);/document.selectAllElements(“.my-class”);/ so to speak.

Posted by Dion Almaer at 6:49 am
9 Comments

+++--
3.8 rating from 12 votes

9 Comments »

Comments feed TrackBack URI

Note that the names have once again been changed since the linked working draft. It’s now querySelector() and querySelectorAll(), see http://dev.w3.org/2006/webapi/selectors-api/Overview.html

Comment by David HÃ¥säther — August 29, 2007

Does Microsoft/IE going to support them?

Comment by Venkat — August 29, 2007

@David – the spec you link to is from 2006. The final names are selectElement() and selectAllElements().

Comment by Dean Edwards — August 29, 2007

s/tomb/tome/

Comment by Andy — August 29, 2007

@Dean: nope, the names were later changed, see http://lists.w3.org/Archives/Public/public-webapi/2007Aug/0067.html :-)

Comment by David HÃ¥säther — August 29, 2007

@David – it looks like you are right. I’ve emailed Lachlan for a final clarification. Still, they can always change their minds again..

Comment by Dean Edwards — August 29, 2007

I just got a response from Lachlan:

[quote]
I got overruled! :-( We ended up holding a working group vote and querySelector/querySelectorAll won.

http://lists.w3.org/Archives/Public/public-webapi/2007Aug/0066.html
http://www.w3.org/2002/09/wbs/38482/selectorsNames/results
[/quote]

Comment by Dean Edwards — August 29, 2007

I would love to see a study which demonstrates that a shorter name “improves the readability of the source code”. My entire body of experience suggests the opposite.

Also, if you’re spending most of your development time typing, you’re doing something wrong anyway. Do you really think you waste more than a few minutes a day typing long names instead of short ones?

Comment by Travis Wilson — August 30, 2007

I think longer, more descriptive names are generally better than shorter, less “clear” names.

Comment by LKM — September 4, 2007

Leave a comment

You must be logged in to post a comment.