Editorial note about Map/Set equality algorithm needs updating

[Josh-Cena]

After https://github.com/tc39/ecma262/pull/3337, Map/Set key equality no longer uses SameValueZero. The editorial note in several places need updating:

• https://tc39.es/ecma262/multipage/ecmascript-data-types-and-values.html#_ref_89
• https://tc39.es/ecma262/multipage/keyed-collections.html#_ref_13180
• https://tc39.es/ecma262/multipage/keyed-collections.html#_ref_13291

FWIW, I am much in favor of sticking to SameValueZero in the algorithms, because it helps readers understand better what's going on even without realizing that keys are canonicalized, but in the current form it seems to present more confusions. See also https://github.com/mdn/content/pull/36698.

[bakkot]

Eh... I think it's fine to describe the way Maps compare keys as "using SameValueZero" even though mechanically the algorithms are written to canonicalize and then use SameValue. There's not actually a difference.

[Josh-Cena]

But either way people are confused:

• If the editorial note says "SameValueZero" then people will say "but the actual algorithm doesn't!"
• If the editorial note says "SameValue" then it's easily misread without a caveat everywhere that keys are canonicalized, which seems more heavyweight.

OTOH if the algorithm uses SameValueZero, we ease all these mental burdens for free.

[bakkot]

At the cost of not using the same operation when adding/deleting vs querying, yes, but that's confusing in a different way.

Thoughts on adding a NOTE above the various if _p_.[[Key]] is _key_ steps which says something like "The use of CanonicalizeKeyedCollectionKey above makes this equivalent to SameValueZero"?

[Josh-Cena]

If I shall ask: how is adding/deleting vs querying different if we need to canonicalize every input anyway?

[bakkot]

I'm afraid I don't understand the question; can you rephrase?

If you're asking why we need to canonicalize when adding, it's because otherwise we'd have to canonicalize when iterating over the contents of the data structure, and it's conceptually cleaner to do it on input rather than output.

[Josh-Cena]

I'm asking about this:

At the cost of not using the same operation when adding/deleting vs querying

I was supposing that the keys are canonicalized at the input boundary, so I'm not sure why these methods would not all be able to use SameValueZero.

[bakkot]

If the keys are canonicalized at the input boundary then there is no reason to use SameValueZero. SameValueZero is just SameValue plus special handling for -0, but if you canonicalize then -0 can't be an input.

[Josh-Cena]

Yes, but our point is that although SameValueZero and SameValue are operationally equivalent in this case, using the former in the algorithm lowers a lot of cognitive burden for readers, because if you use SameValue, then explaining it as either SameValueZero or SameValue in prose doesn't make much sense.

[bakkot]

3490