Skip to content

Commit 06c0232

Browse files
authored
Meta: Add element/property ordering guidance to style guide (#831)
1 parent 602aaf0 commit 06c0232

File tree

1 file changed

+23
-1
lines changed

1 file changed

+23
-1
lines changed

docs/style-guide.md

+23-1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ This document is an evolving list of recommendations for the ECMA-402 specificat
44

55
This document contains background on how the style decisions were reached. The actual recommendations are highlighted with a :star2: emoji.
66

7+
78
## Table of Contents
89

910
- [Casing Conventions](#casing-conventions)
@@ -27,7 +28,9 @@ This document contains background on how the style decisions were reached. The
2728
- [Pros](#pros-3)
2829
- [Cons](#cons-3)
2930
- [Decision](#decision-3)
30-
31+
- [Element Ordering](#element-ordering)
32+
- [General Guidelines](#general-guidelines)
33+
- [resolvedOptions](#resolvedoptions)
3134

3235
*Table of Contents generated using https://magnetikonline.github.io/markdown-toc-generate/*
3336

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

201204
- Defer the decision on the syntax for identifiers to the other specification when possible.
205+
206+
## Element Ordering
207+
208+
This section concerns the observable order for elements of arrays and properties of objects.
209+
210+
### General Guidelines
211+
212+
:star2: *ECMA-402 must provide a deterministic order for the elements of all arrays and the properties of all objects. This order should be lexicographic except in cases for which there is a clearly preferable semantic ordering. :star2:*
213+
214+
For example, an array holding the time zone identifiers "Asia/Tokyo", "Asia/Ho_Chi_Minh", and "Asia/Dubai" should use the order `["Asia/Dubai", "Asia/Ho_Chi_Minh", "Asia/Tokyo"]`
215+
216+
For an example of when *not* to use lexicographic order, consider an array holding calendar time scale units. This array could be ordered by descending magnitude as `["years", "months", "weeks", "days"]` or its reverse ascending magnitude as `["days", "weeks", "months", "years"]`, but should not use the lexicographic `["days", "months", "weeks", "years"]` order.
217+
218+
### `resolvedOptions`
219+
: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:
220+
221+
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.
222+
#### Examples
223+
`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`.

0 commit comments

Comments
 (0)