document that strings-as-enums are kebab-case

[bakkot]

No description provided.

[sffc]

This directly contradicts the ECMA-402 style guide.

https://github.com/tc39/ecma402/blob/main/docs/style-guide.md#identifiers-defined-by-ecma-402

[sffc]

Doing some archaeology, this ECMA-402 style was approved in the October 2019 TC39 meeting.

PR: tc39/ecma402#377

Notes: https://github.com/tc39/notes/blob/main/meetings/2019-10/october-2.md#revisit-ecma-402-casing-conventions

[bakkot]

Ah, thanks for the pointer. That's... unfortunate. I don't understand the decision to go against W3C guidelines within 402 and I don't think it makes sense to continue to violate those for new APIs.

[sffc]

The reasons behind the ECMA-402 style are well documented in the style guide doc. There were few if any string enumerations in ECMA-262 at the time, but since then, this style was adopted by Temporal (the value of the roundingMode enum).

[bakkot]

There was already Atomics.wait at the time, and the base64 proposal has now shipped with stop-before-partial, so weight of precedent within 262 continues to be kebab-case.

But also, the weight of precedent on the web platform is very heavily for kebab-case, following W3C guidelines. Off the top of my head, at least fetch (in a bunch of places), PerformanceObserver entries, navigator.permissions, document.featurePolicy, WebAuthn, CompressionStream... I'm sure there's more, web platform is huge.

It's not like the web platform is entirely consistent either, but I'll argue it's best not to intentionally deviate except in cases where there is specific reason to do so.

[sffc]

The Atomics.wait string enumeration was at Stage 3, I believe, when this style guide was considered. I haven't been policing other proposals since then; maybe I should have been.

To be clear, I'm not super strongly attached to the ECMA-402 convention, despite being the one who proposed it. There were a number of reasons camel case had technical merit, specifically the ability for the enumeration values to be used as identifiers, and we didn't put a lot of weight on matching W3C style. Perhaps we should have put more weight on matching W3C style at the time. But, now that we do have that style, I think it's just as important for ECMA-262 to be self-consistent with ECMA-402 as it is to be consistent with other web platform APIs.

[bakkot]

That's a reasonable position which I disagree with. Many more JS programmers are going to run into fetch's no-cors than are going to run into Intl's halfCeil or morePrecision. More broadly, the web platform is not going to change this guidance given how many enum values they already have, so we can either try to be consistent going forward with a finite and relatively short list of legacy inconsistencies, or we continue to add new inconsistencies in new proposals.

I've increased the timebox for the agenda item so we can talk about it in plenary.

[eemeli]

One place where this seems quite relevant is the roundingMode option of the Amount constructor, which is intended to match the capabilites of Intl.NumberFormat, where the corresponding option supports the values "halfCeil", "halfFloor", "halfExpand", "halfTrunc", "halfEven", among others.

If this normative convention is adopted, should the Amount option values match Intl.NumberFormat, or use kebab-case ("half-ceil", "half-floor", etc.)?

[bakkot]

These rules are all intended to be general guidelines, not hard-and-fast rules. In cases where there's strong reason to deviate that's fine. In that case I'd say the fact that these specific enum values are also used in different APIs is strong reason to match the existing APIs instead of following the guideline.

[bakkot]

Per discussion in plenary: this applies to 262, but not 402 except in cases where TG2 thinks it should. Also, in the case of Temporal and Amount and any other APIs which are adopting existing enums which currently violate this convention, they should match existing spelling rather than trying to keep to this convention.

[ctcpip]

this applies to 262, but not 402 except in cases where TG2 thinks it should

should this be documented here then?

[bakkot]

Added a sentence to that effect:

ECMA-402 has historically followed a different convention; as such this convention does not automatically apply to enums defined in that specification.

[michaelficarra]

You should actually restate the convention in the paragraph here. I don't want the convention to only be described in the section heading.

[bakkot]

Done:

When a string is serving as an enum value, in any position (including arguments and return values), that string should be lowercase and words in it should be separated by dashes rather than spaces.

[michaelficarra]

What does this add? What's the alternative? Say "as opposed to ...".

[bakkot]

This was a request from Mark. As opposed to, I guess, random other punctuators? I would prefer to leave this as-is.

[michaelficarra]

I just can't imagine what someone would want to put there that's not alphanumeric. If this isn't a reasonable expectation, I don't see why we would want to say anything about it. We also don't want to put ZWNJs between the hyphens, but nobody wants to do that, so I don't think it needs mentioning.

[bakkot]

Again, this was a specific request in plenary. I'm not going to remove it without going through plenary again, and I'm not going to do that. It's not hurting anything.

[ctcpip]

Suggested change

	When a string is serving as an enum value, in any position (including arguments and return values), that string should be lowercase and words in it should be separated by dashes rather than spaces. For example, `Atomics.wait` returns one of the three strings `"not-equal"`, `"ok"`, or `"timed-out"`, and `Uint8Array.prototype.setFromBase64` takes an argument with possible values `"loose"`, `"strict"`, or `"stop-before-partial"`.
	The content between the dashes should generally be alphanumeric.
	When a string is serving as an enum value, in any position (including arguments and return values), that string should be lowercase and words in it should be separated by hyphens. For example, `Atomics.wait` returns one of the three strings `"not-equal"`, `"ok"`, or `"timed-out"`, and `Uint8Array.prototype.setFromBase64` takes an argument with possible values `"loose"`, `"strict"`, or `"stop-before-partial"`.
	Content between hyphens should be alphanumeric.

hyphens !== dashes and 'generally' was not doing any work here 😊

edit: also removed "rather than spaces" because spaces is not the only alternative. (but this is more of a nit than anything else)

edit 2: removed definite articles which were also not doing any work