W3C home > Mailing lists > Public > public-webapi@w3.org > December 2006

Re: Selectors API naming

From: Martijn <martijn.martijn@gmail.com>
Date: Sun, 24 Dec 2006 16:26:51 +0100
Message-ID: <6c97b8b10612240726w5247824el3ac2b69f1fa0ead6@mail.gmail.com>
To: "Maciej Stachowiak" <mjs@apple.com>
Cc: "Christophe Jolif" <cjolif@ilog.fr>, "Dave Massy" <Dave.Massy@microsoft.com>, "Anne van Kesteren" <annevk@opera.com>, "Charles McCathieNevile" <chaals@opera.com>, public-webapi@w3.org

On 12/23/06, Maciej Stachowiak <mjs@apple.com> wrote:
> I stand by my argument, which was about readability, not "ease of
> use". I disagree that there is a fundamental distinction between APIs
> and languages. Languages after all have a standard library, which is
> an API. Consider a hypothetical graphics API:

And a language is easier to learn when the standard library has been
logically set up.
document.matchAll is deviating from that.
Document.getElementsBySelector has a higher readability in that regard
I think.

> // wouldn't want to mistake these for a point made in a debate!
> CoordinateSystemPoint translate(CoordinateSystemPoint point, float
> horizontalDelta, float verticalDelta)
> {
>      point.horizontalCoordinate += horizontalDelta;
>      point.verticalCoordinate += verticalDelta;
>      return point;
> }
>
>
> Most graphics APIs instead do it more like this:
>
> Point translate(Point point, float xDelta, float yDelta)
> {
>      point.x += xDelta;
>      point.y += yDelta;
>      return point;
> }
>
> I think most reasonable people would agree that this is better.
> Graphics code will probably spend a lot of time dealing with points
> (and rarely with other possible meanings for "x", "y" and "point").

Well, .x and .y are derived from a point object, that's why it works
in that case.
I think document.x and document.y are a whole lot less clearer.

document.matchAll will not nearly be used as much so the cost of
learning is relatively much higher than
document.getElementsBySelector, which is easier to learn because it is
consistent with the other, similar named methods.

> It is somewhat debatable whether finding elements by selector would
> be as fundamental in the DOM as points are in graphics APIs, but I
> think there is at least some evidence to that effect.

I don't think that's nearly as fundamental as points in a graphics API.

I think there are 2 problems with current naming
- It's too generic. Instead of matchAll, it could have been named
getAll, collectAll, etc.
- It is inconsistent with current naming. Isn't there a need/desire
for the w3c to be consistent with the naming of new methods regarding
older specs?

Regards,
Martijn

-- 
Martijn Wargers
Help Mozilla!
http://weblogs.mozillazine.org/qa/
http://www.mozilla.org/contribute/
Received on Sunday, 24 December 2006 15:27:03 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:18:56 GMT