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 3 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
6 changes: 6 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,9 @@ 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

I.e., lowercase and dash-delimited. 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"`.
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.

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

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.

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.


The pieces between the dashes should generally be alphanumeric.
Comment thread
bakkot marked this conversation as resolved.
Outdated