Re: Selectors API naming

Hello Web API interested parties,

I've read this thread, and rather than replying to people's specific  
points, I would like to give some arguments in favor of a relatively  
short name.

Short Names For Common Idioms
---------------------------------------

Many have argued that classes, methods and properties should have  
clear, descriptive names. I agree with this general principle.  
However, I think the main reason for this is not learnability, but  
readability of resulting code. Ideally, well-written code using  
standard methods should be easy to understand and modify. Maintenance  
is a much larger part of the life cycle and development cost of most  
code than initial development.

Given this, there is a counterbalancing principle that common  
fundamental idioms should have short names. That's because these  
basic idioms become so well understood that extra verbosity just  
creates visual noise. I think in extreme cases of this, most people  
would agree.

Some examples:

Consider if in C++, the end of statement token was not the brief but  
arbitrary ";", but the far more explicit "end_of_statement". Reading  
code like this:

int x = get_value() end_of_statement
int y = x + 3 end_of_statement
printf("%d\n", y) end_of_statement

is way harder than the standard version:

int x = get_value();
int y = x + 3;
printf("%d\n", y);

Another idiom that is given a very brief lexical form in most  
languages is access to variables. Access to a variable for either  
reading or writing generally requires either a short single-character  
token (like $ in perl) or no decoration at all but just the variable  
name. ECMAScript could be much more explicit, and make you clearly  
identify your global and local variable references:

function addTag(tag)
{
     getReferenceByGlobalVariableName("allTags") =  
getReferenceByLocalVariableName("tag");
}

But of course code like that would be wildly unreadable.

I hope we will all agree, given these examples, that very common  
constructs should be expressible concisely. Autocomplete may make  
long names easier to type, but it does not make the resulting code  
any easier to read.


Will Selectors API be a Common Idiom?
---------------------------------------------

Now, the remaining question is whether the proposed Selectors API  
would be widely enough used to merit special short names, and if so  
how short. Here are some arguments that it merits a short name:

1) The DOM holds a large proportion of the information that most DOM  
scripts manipulate. Access to DOM elements is arguably analogous to  
access to variables, though of course not as common.

2) The Selectors API methods provide an improved superset of the  
capabilities of getElement(s)By{Id,TagName,Name,ClassName}. They do  
not suffer from the flaw of returning live lists. And they align well  
with the use of selectors with CSS in the web platform - using  
selectors to find nodes and process data or attach behavior lines up  
well with using them to attach presentational style. Therefore, if  
implemented interoperably, they are likely to be used quite widely.

3) There is some evidence, based on the shortcuts found in JS  
libraries, that document.getElementById is too long a name for how  
commonly this method is used. Some have argued that any name would be  
given a short alias, but I do not buy this; document.all seems short  
enough that no one needs a shortcut.

Based on this, I think that shorter names like "match" or "matchAll"  
are justified, if not necessarily those exact names.


Response to Some Other Arguments
------------------------------------------

- "These might conflict with short names in markup" -- I don't see  
why markup should get all the short names and script should be stuck  
with verbose ones. Also, the HTMLDocument interface (which it's  
likely will have to be implemented on every document in a browser for  
CDI to work sanely) already steps on such useful short names as  
"title", "URL", "images", "open", "close"...

- "It doesn't match names of other similar methods" -- I think  
selectSingleNode proves that slight inconsistency is not much of a  
problem in practice.

- "It will be too hard to learn" -- If all names were this pithy this  
might be true. But as it is I doubt it adds much to the learning curve.

- "Microsoft representatives endorse a longer name" -- I don't think  
Microsoft's track record in design of web APIs for JavaScript  
justifies treating them as an authority. I hope their arguments will  
be evaluated on their merits, not the credentials of the speakers,  
and I would ask the same for mine.


In conclusion, I think there is a strong case for short names. If  
"match" and "matchAll" are objectionable, I hope others will consider  
proposing some alternative relatively short names.

Regards,
Maciej

Received on Friday, 22 December 2006 01:49:21 UTC