Skip to content

document that strings-as-enums are kebab-case #165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bakkot wants to merge 6 commits into
base: main
Choose a base branch
from
Open

document that strings-as-enums are kebab-case #165

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2a18137
document that strings-as-enums are kebab-case
bakkot Sep 15, 2025
c0e1f6a
Update normative-conventions.md
bakkot Sep 15, 2025
dd616a5
tweak wording, mention alphanumeric
bakkot Sep 23, 2025
d7abc4e
mention 402 convention
bakkot Sep 24, 2025
b25ebf9
Update normative-conventions.md
bakkot Sep 24, 2025
131ae36
restate convention
bakkot Sep 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions normative-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,11 @@ Any time an iterable or async-iterable value (a value that has a `Symbol.iterato
Although primitive Strings are default iterable (`String.prototype` has a `Symbol.iterator` method which enumerates code points), it is now considered a mistake to iterate a String without specifying whether the String is providing an abstraction over code units, code points, grapheme clusters, or something else.

NB: This convention is new as of 2024, and most earlier parts of the language do not follow it. In particular, positional destructuring (both binding and assignment), array spread, argument spread, for-of loops, `yield *`, the `Set` and `AggregateError` constructors, `Object.groupBy`, `Map.groupBy`, `Promise.all`, `Promise.allSettled`, `Promise.any`, `Promise.race`, `Array.from`, the static `from` methods on typed array constructors, and `Iterator.from` (Stage 3 at time of writing) all accept primitives where iterables are expected.

## Multi-word strings which are serving as enum values should be kebab-case

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.
Copy link
Copy Markdown
Member

@michaelficarra michaelficarra Sep 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@bakkot bakkot Sep 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

@michaelficarra michaelficarra Sep 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

@bakkot bakkot Sep 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +51 to +53
Copy link
Copy Markdown
Member

@ctcpip ctcpip Sep 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


ECMA-402 has historically followed [a different convention](https://github.com/tc39/ecma402/blob/main/docs/style-guide.md#identifiers-defined-by-ecma-402); as such this convention does not automatically apply to enums defined in that specification.