tc39
document that strings-as-enums are kebab-case
Doing some archaeology, this ECMA-402 style was approved in the October 2019 TC39 meeting.
PR: https://github.com/tc39/ecma402/pull/377
Notes: https://github.com/tc39/notes/blob/main/meetings/2019-10/october-2.md#revisit-ecma-402-casing-conventions
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.
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).
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.
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.
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.
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.)?
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.
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.
this applies to 262, but not 402 except in cases where TG2 thinks it should
should this be documented here then?
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.