W3C home > Mailing lists > Public > whatwg@whatwg.org > January 2015

Re: [whatwg] Confusion about node1.replace(node2)

From: James M. Greene <james.m.greene@gmail.com>
Date: Sat, 10 Jan 2015 07:14:10 -0600
Message-ID: <CALrbKZhHGxVpP8Ljgpuu=D_=jpmYvPipuwJfkxn_8kiXiy6eNg@mail.gmail.com>
To: Glen Huang <curvedmark@gmail.com>
Cc: whatwg <whatwg@whatwg.org>
I have to agree with Glen on this one. Using `node1.replace(node2);` makes
me expect that `node1` will be replacing by `node2`.

jQuery is famous (and sometimes infamous, depending on who you talk to) for
its API brevity and yet we still chose longer names[1] for these scenarios:
`replaceWith` and `replaceAll` (even including "All" in the latter to
clarify that it operates on the entire context set, not just the first
element).

Dojo uses the same method names[2] as well for their NodeList
implementation: `replaceWith` and `replaceAll`.

If not renamed, `ChildNode#replace` will probably need to be added to my
personal list DOM APIs that I'm always doubtful of how to use despite years
of off-and on usage... along with, e.g. `ParentNode#insertBefore` and
`ParentNode#insertAfter` for their parameter order.

[1]: http://api.jquery.com/category/manipulation/dom-replacement/

[2]: http://dojotoolkit.org/api/1.10/dojo/NodeList.html

Sincerely,
   James Greene
On Jan 10, 2015 3:56 AM, "Glen Huang" <curvedmark@gmail.com> wrote:

> > And since methods operate on the object they are invoked upon I think
> the name is clear
> > enough.
>
> The fact replace() is a method operating on an object doesn’t clarify the
> intention in this case,because the confusion here is that it’s unclear
> whether the object is having others take its place, or is itself trying
> take others’ place, and from the general meaning of the english word
> “replace”, it actually implies the latter.
>
> > The general preference is brevity over precision.
>
> In most cases, I favor brevity too, but when it starts to raise confusion,
> especially it’s implying the opposite of what it’s actually trying to do,
> brevity should no longer be a priority, IMHO.
Received on Saturday, 10 January 2015 23:30:31 UTC

This archive was generated by hypermail 2.3.1 : Monday, 13 April 2015 23:09:32 UTC