Meta: Update style guide to discuss preferred orderings of elements #831

ben-allen · 2023-08-31T21:08:38Z

Toward #578

1795b9d inspired by #578
29e183b inspired by tc39/proposal-intl-duration-format#163

docs/style-guide.md

sffc · 2023-09-18T21:24:08Z

docs/style-guide.md

+### `resolvedOptions`
+
+:star2: The `resolvedOptions` of Intl objects should appear in the following order: 
+
+1. `locale`
+2. All properties (given in lexicographical order) that can be set by extension keys and that are guaranteed to exist
+3. Properties (in lexicographical order) that are not set by extension keys and that are guaranteed to exist 
+4. All properties (in lexicographical order) that exist conditionally. :star2:


@gibson042 for feedback on this ordering

It seems insufficiently stable to me, because we are currently contemplating adding support for -u- extension keys that can currently only be set by options, and could definitely promote a conditional property to mandatory in the future.

Suggested change

### `resolvedOptions`

:star2: The `resolvedOptions` of Intl objects should appear in the following order:

1. `locale`

2. All properties (given in lexicographical order) that can be set by extension keys and that are guaranteed to exist

3. Properties (in lexicographical order) that are not set by extension keys and that are guaranteed to exist

4. All properties (in lexicographical order) that exist conditionally. :star2:

### `resolvedOptions`

:star2: *Properties in the output from `resolvedOptions()` of an Intl object should start with `locale` and otherwise use lexicographic order. Deviations (such as those motivated by semantic order involving a subset of properties) must be documented.* :star2:

Spec changes that add properties should do so in accordance with this recommendation, rather than automatically placing them at the end—relative enumeration order of properties should remain stable over time, but there is no such expectation regarding adjacency.

#### Examples

`Object.keys(new Intl.Segmenter().resolvedOptions())` returns `[ 'locale', 'granularity' ]`. If support for the [Unicode BCP 47 U Extension "dx" key](https://unicode.org/reports/tr35/#UnicodeDictionaryBreakExclusionIdentifier) were added and exposed as `dictionaryBreakExcludedScripts`, that property would belong before `granularity`.

docs/style-guide.md

gibson042 · 2023-09-19T23:12:39Z

docs/style-guide.md

+
+## Element Ordering
+
+This section concerns the order in which containers store elements. 


What is the definition of "container" in this context?

Suggested change

This section concerns the order in which containers store elements.

This section concerns the order in which properties are stored and accessed within plain objects.

Does this apply outside of plain objects?

docs/style-guide.md

gibson042 · 2023-09-19T23:58:58Z

docs/style-guide.md

+### `resolvedOptions`
+
+:star2: The `resolvedOptions` of Intl objects should appear in the following order: 
+
+1. `locale`
+2. All properties (given in lexicographical order) that can be set by extension keys and that are guaranteed to exist
+3. Properties (in lexicographical order) that are not set by extension keys and that are guaranteed to exist 
+4. All properties (in lexicographical order) that exist conditionally. :star2:


It seems insufficiently stable to me, because we are currently contemplating adding support for -u- extension keys that can currently only be set by options, and could definitely promote a conditional property to mandatory in the future.

Suggested change

### `resolvedOptions`

:star2: The `resolvedOptions` of Intl objects should appear in the following order:

1. `locale`

2. All properties (given in lexicographical order) that can be set by extension keys and that are guaranteed to exist

3. Properties (in lexicographical order) that are not set by extension keys and that are guaranteed to exist

4. All properties (in lexicographical order) that exist conditionally. :star2:

### `resolvedOptions`

:star2: *Properties in the output from `resolvedOptions()` of an Intl object should start with `locale` and otherwise use lexicographic order. Deviations (such as those motivated by semantic order involving a subset of properties) must be documented.* :star2:

Spec changes that add properties should do so in accordance with this recommendation, rather than automatically placing them at the end—relative enumeration order of properties should remain stable over time, but there is no such expectation regarding adjacency.

#### Examples

`Object.keys(new Intl.Segmenter().resolvedOptions())` returns `[ 'locale', 'granularity' ]`. If support for the [Unicode BCP 47 U Extension "dx" key](https://unicode.org/reports/tr35/#UnicodeDictionaryBreakExclusionIdentifier) were added and exposed as `dictionaryBreakExcludedScripts`, that property would belong before `granularity`.

ryzokuken · 2023-09-26T14:11:36Z

docs/style-guide.md

+		- [Examples](#examples)
+		- [Alternative: Kebab case for all string enumerations](#alternative-kebab-case-for-all-string-enumerations)
+			- [Pros](#pros)
+			- [Cons](#cons)
+			- [Decision](#decision)
+		- [Alternative: Kebab case for new identifiers only](#alternative-kebab-case-for-new-identifiers-only)
+			- [Pros](#pros-1)
+			- [Cons](#cons-1)
+			- [Decision](#decision-1)
+		- [Alternative: Use kebab case but also accept camel case](#alternative-use-kebab-case-but-also-accept-camel-case)
+			- [Pros](#pros-2)
+			- [Cons](#cons-2)
+			- [Decision](#decision-2)
+	- [Identifiers defined outside ECMA-402](#identifiers-defined-outside-ecma-402)
+		- [Examples](#examples-1)
+		- [Alternative: Convert identifiers to camel case](#alternative-convert-identifiers-to-camel-case)
+			- [Pros](#pros-3)
+			- [Cons](#cons-3)
+			- [Decision](#decision-3)


Are the whitespace changes necessary?

changed it back to the previous spacing

The previous spacing was 4 spaces and your new version has 2 spaces 🙈

ryzokuken

Some old comments and some new ones, let's clean this one up!

ryzokuken · 2023-09-26T14:13:01Z

docs/style-guide.md

+
+## Element Ordering
+
+This section concerns the order in which containers store elements. 


Suggested change

This section concerns the order in which containers store elements.

This section concerns the order in which properties are stored and accessed within plain objects.

Does this apply outside of plain objects?

docs/style-guide.md

ryzokuken · 2024-02-22T15:31:04Z

docs/style-guide.md

+		- [Examples](#examples)
+		- [Alternative: Kebab case for all string enumerations](#alternative-kebab-case-for-all-string-enumerations)
+			- [Pros](#pros)
+			- [Cons](#cons)
+			- [Decision](#decision)
+		- [Alternative: Kebab case for new identifiers only](#alternative-kebab-case-for-new-identifiers-only)
+			- [Pros](#pros-1)
+			- [Cons](#cons-1)
+			- [Decision](#decision-1)
+		- [Alternative: Use kebab case but also accept camel case](#alternative-use-kebab-case-but-also-accept-camel-case)
+			- [Pros](#pros-2)
+			- [Cons](#cons-2)
+			- [Decision](#decision-2)
+	- [Identifiers defined outside ECMA-402](#identifiers-defined-outside-ecma-402)
+		- [Examples](#examples-1)
+		- [Alternative: Convert identifiers to camel case](#alternative-convert-identifiers-to-camel-case)
+			- [Pros](#pros-3)
+			- [Cons](#cons-3)
+			- [Decision](#decision-3)


The previous spacing was 4 spaces and your new version has 2 spaces 🙈

sffc · 2024-05-02T23:00:38Z

docs/style-guide.md

@@ -199,3 +201,22 @@ We could enforce a camel case convention on these strings, such as the following
 ##### Decision

 - Defer the decision on the syntax for identifiers to the other specification when possible.
+


@ben-allen Please make sure this fully fixes #578

Actually we should follow this up with a normative PR for PluralRules.

…ions ordering

ryzokuken

Overall LGTM, thanks!

ryzokuken · 2024-05-06T17:26:24Z

docs/style-guide.md

+:star2: <em>The `resolvedOptions` of Intl objects should appear in the following order: 
+
+1. `locale`
+2. All properties (given in lexicographical order) that can be set by extension keys and that are guaranteed to exist
+3. Properties (in lexicographical order) that are not set by extension keys and that are guaranteed to exist 
+4. All properties (in lexicographical order) that exist conditionally.</em> :star2:


Is this whole section purposefully italicized?

Yes, to match the italicization in the other starred blocks. I do admit that italicizing the list might be a situation where the result of insisting on consistency is ugly enough that it's the wrong thing to do.

I think one way to do it would be to rephrase the first sentence into a summarized guideline, star+italicize it and follow that with the full list. An entire list being starred/italicized doesn't really say much and looks weird.

ben-allen · 2024-05-06T18:17:14Z

@gibson042 what do you think about this version?

…edOptions`" list

…`resolvedOptions`" list

gibson042 · 2024-05-16T16:08:12Z

docs/style-guide.md

+    - [Element Ordering](#element-ordering)
+	      - [General Guidelines](#general-guidelines)
+	      - [resolvedOptions](#resolvedoptions)


The extra indentation here breaks Markdown list output: https://github.com/tc39/ecma402/blob/97ba211cddb8a4a22f67e327af05372b545f2bcd/docs/style-guide.md#table-of-contents:~:text=Element%20Ordering

Suggested change

- [Element Ordering](#element-ordering)

- [General Guidelines](#general-guidelines)

- [resolvedOptions](#resolvedoptions)

- [Element Ordering](#element-ordering)

- [General Guidelines](#general-guidelines)

- [resolvedOptions](#resolvedoptions)

docs/style-guide.md

gibson042 · 2024-05-16T16:42:31Z

docs/style-guide.md

+### `resolvedOptions`
+
+:star2: *The `resolvedOptions` of `Intl` objects should appear with `locale` first, followed by properties guaranteed to exist that can be set via extension keys, followed by properties guaranteed to exist that are not set by extension keys, and then finally all properties that exist conditionally. Elements in each of these categories should appear in lexicographical order.* :star2:
+
+Order of `resolvedOptions`:
+1. `locale`
+2. All properties (given in lexicographical order) that can be set by extension keys and that are guaranteed to exist
+3. Properties (in lexicographical order) that are not set by extension keys and that are guaranteed to exist 
+4. All properties (in lexicographical order) that exist conditionally.


Reiterating #831 (comment) :

Suggested change

### `resolvedOptions`

:star2: *The `resolvedOptions` of `Intl` objects should appear with `locale` first, followed by properties guaranteed to exist that can be set via extension keys, followed by properties guaranteed to exist that are not set by extension keys, and then finally all properties that exist conditionally. Elements in each of these categories should appear in lexicographical order.* :star2:

Order of `resolvedOptions`:

1. `locale`

2. All properties (given in lexicographical order) that can be set by extension keys and that are guaranteed to exist

3. Properties (in lexicographical order) that are not set by extension keys and that are guaranteed to exist

4. All properties (in lexicographical order) that exist conditionally.

### `resolvedOptions`

:star2: *Properties in the output from `resolvedOptions()` of an Intl object should start with `locale` and otherwise use lexicographic order. Deviations (such as those motivated by semantic order involving a subset of properties) must be documented.* :star2:

Spec changes that add properties should do so in accordance with this recommendation, rather than automatically placing them at the end—relative enumeration order of properties should remain stable over time, but there is no such expectation regarding adjacency.

#### Examples

`Object.keys(new Intl.Segmenter().resolvedOptions())` returns `[ 'locale', 'granularity' ]`. If support for the [Unicode BCP 47 U Extension "dx" key](https://unicode.org/reports/tr35/#UnicodeDictionaryBreakExclusionIdentifier) were added and exposed as `dictionaryBreakExcludedScripts`, that property would belong before `granularity`.

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

sffc changed the title ~~Update style guide to discuss preferred orderings of elements~~ Meta: Update style guide to discuss preferred orderings of elements Sep 18, 2023

sffc reviewed Sep 18, 2023

View reviewed changes

gibson042 requested changes Sep 19, 2023

View reviewed changes

ryzokuken reviewed Sep 26, 2023

View reviewed changes

ben-allen force-pushed the update-readme-note-on-ordering branch from 5a261af to 1ef3e6a Compare October 12, 2023 16:58

ryzokuken approved these changes Feb 22, 2024

View reviewed changes

ryzokuken added the meta label Feb 22, 2024

sffc reviewed May 2, 2024

View reviewed changes

ben-allen force-pushed the update-readme-note-on-ordering branch 2 times, most recently from f37490f to bafaa25 Compare May 4, 2024 17:30

Meta: added notes in style guide on element ordering and resolved opt…

1a826c9

…ions ordering

ben-allen force-pushed the update-readme-note-on-ordering branch from bafaa25 to 1a826c9 Compare May 4, 2024 17:31

ben-allen requested a review from gibson042 May 6, 2024 17:25

ryzokuken approved these changes May 6, 2024

View reviewed changes

Meta: Updated to incorporate feedback on italics in "order of `resolv…

83a6734

…edOptions`" list

ben-allen force-pushed the update-readme-note-on-ordering branch from 2404d76 to 83a6734 Compare May 7, 2024 18:53

fixup! Meta: Updated to incorporate feedback on italics in "order of …

97ba211

…`resolvedOptions`" list

gibson042 requested changes May 16, 2024

View reviewed changes

ben-allen and others added 2 commits May 21, 2024 12:05

Update docs/style-guide.md

3895c86

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

Update docs/style-guide.md

b612945

Co-authored-by: Richard Gibson <richard.gibson@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Meta: Update style guide to discuss preferred orderings of elements #831

Meta: Update style guide to discuss preferred orderings of elements #831

ben-allen commented Aug 31, 2023 •

edited by sffc

sffc Sep 18, 2023

gibson042 Sep 19, 2023

gibson042 Sep 19, 2023

ryzokuken Sep 26, 2023

gibson042 Sep 19, 2023

ryzokuken Sep 26, 2023

ben-allen Oct 12, 2023

ryzokuken Feb 22, 2024

ryzokuken left a comment

ryzokuken Sep 26, 2023

ryzokuken Feb 22, 2024

sffc May 2, 2024

sffc May 2, 2024

ryzokuken left a comment

ryzokuken May 6, 2024

ben-allen May 6, 2024

ryzokuken May 7, 2024

ben-allen commented May 6, 2024

gibson042 May 16, 2024

gibson042 May 16, 2024


		## Element Ordering

		This section concerns the order in which containers store elements.

		@@ -199,3 +201,22 @@ We could enforce a camel case convention on these strings, such as the following
		##### Decision

		- Defer the decision on the syntax for identifiers to the other specification when possible.

Meta: Update style guide to discuss preferred orderings of elements #831

Are you sure you want to change the base?

Meta: Update style guide to discuss preferred orderings of elements #831

Conversation

ben-allen commented Aug 31, 2023 • edited by sffc

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ryzokuken left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ryzokuken left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ben-allen commented May 6, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ben-allen commented Aug 31, 2023 •

edited by sffc