W3C home > Mailing lists > Public > www-dom@w3.org > July to September 2012

Re: DOM 4 naming "before" and "after"

From: Maciej Stachowiak <mjs@apple.com>
Date: Wed, 29 Aug 2012 23:52:57 -0700
Cc: Joćo Eiras <joaoe@opera.com>, "www-dom@w3.org" <www-dom@w3.org>
Message-id: <B9BCFBDB-5FE1-4F1E-A1DD-0C25900F5F1A@apple.com>
To: Anne van Kesteren <annevk@annevk.nl>

On Aug 26, 2012, at 6:40 AM, Anne van Kesteren <annevk@annevk.nl> wrote:

> On Wed, Aug 22, 2012 at 11:37 PM, Joćo Eiras <joaoe@opera.com> wrote:
>> However the baseline APIs provided by browser should be designed for
>> clarity. While it's optional to learn to use a library, it's not as often
>> optional to learn the APIs of the web platform.
> 
> Well, there seems to be some sentiment that the platform should be a
> good enough library.
> http://infrequently.org/2012/08/inadmissible-arguments/
> 
> We already have the verb'd variant, insertBefore(). Big reason why we
> added these new methods is to provide short names for common
> operations (also ES6-style API and making it easier to deal with
> text).

The fact that insertBefore() and before() both exist really makes it seem like before() will retrieve what insertBefore() inserts. If it was just a question of an alias with a shorter name, then I guess people could just avoid using or implementing before(). But before() has significant other benefits too - it lets you pass more than one node, it lets you use strings directly, and it operates directly on the node to insert before, rather than requiring you to call the method on the parent, passing the node. It would be nice to have a method with those features and a concise name that sounds like a verb. Ditto for after(). "before" and "after" are 6 and 5 characters respectively. "insertBefore" and "insertAfter" are 12 and 11. How about these pairs:



preInsert / postInsert - 9 / 10 
addBefore / addAfter - 9 / 8
addPre / addPost - 6 / 7   (or preAdd / postAdd at the same length, or preIns / postIns if we want to abbreviate)


The last pair especially is almost confusingly short, but at least they are verbs. Names of operations should be verbs unless they are pure getters IMO. Not only is it weird in code and documentation to have mutators named by nouns, but it also makes it hard to talk about:

Programmer A: It's easy, just before the foo node on the bar node.
Programmer B: wat

The web platform has enough "wat" in it already, let's not add more.

Regards,
Maciej
Received on Thursday, 30 August 2012 06:53:30 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 30 August 2012 06:53:36 GMT