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" <curvedm...@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.
