Skip to content
Open
Changes from all commits
Commits
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
60 changes: 57 additions & 3 deletions docs/style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,19 @@ This document contains background on how the style decisions were reached. The
- [Pros](#pros-3)
- [Cons](#cons-3)
- [Decision](#decision-3)
- [Element Ordering](#element-ordering)
- [General Guidelines](#general-guidelines)
- [resolvedOptions](#resolvedoptions)
- [Element Ordering](#element-ordering)
- [General Guidelines](#general-guidelines)
- [resolvedOptions](#resolvedoptions)
- [Examples](#examples-2)
- [Naming Conventions](#naming-conventions)
- [Avoiding Abbreviations in Property Names and Values](#avoiding-abbreviations-in-property-names-and-values)
- [Guidelines](#guidelines)
- [Rationale](#rationale)
- [Exceptions](#exceptions)
- [Compound Words in Property Names and Values](#compound-words-in-property-names-and-values)
- [Guidelines](#guidelines-1)
- [Rationale](#rationale-1)
- [Open Question: "[...]style" vs. "[...]display" for High-Level Configuration Properties](#open-question-style-vs-display-for-high-level-configuration-properties)

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

Expand Down Expand Up @@ -221,3 +231,47 @@ For an example of when *not* to use lexicographic order, consider an array holdi
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`.

## Naming Conventions

This section provides guidelines for naming conventions in ECMA-402, focusing on clarity, consistency, and adherence to established practices.

### Avoiding Abbreviations in Property Names and Values

:star2: *Property names and values in ECMA-402 should avoid abbreviations to ensure clarity and readability. Use descriptive names that clearly convey their purpose.* :star2:

#### Guidelines

- Use full, descriptive names for properties and values, even if they are longer (good examples: `fractionalSecondDigits`, `minimumSignificantDigits`).
- Avoid cryptic abbreviations or shortened forms that may confuse readers or developers unfamiliar with the context.
- Prioritize clarity over brevity, especially for properties that are frequently used or have significant impact.

#### Rationale

- Descriptive names improve code readability and maintainability.
- They reduce the cognitive load for developers, especially those new to the specification.
Copy link
Contributor

Choose a reason for hiding this comment

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

Also, spelled-out names are more accessible to non-native English speakers, because they are more googlable, etc. We are building an i18n library, after all.

Copy link
Member Author

Choose a reason for hiding this comment

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

What about the immediately following point? I believe it comes close so at the very least I should add something along these lines to it (or after it).

- Avoiding abbreviations aligns with the principle of self-documenting code, making the API easier to understand and use.

#### Exceptions

- Abbreviations may be acceptable if they are widely recognized and standardized (e.g., `UTC`, `ISO`).
- When abbreviations are used, they should be documented thoroughly to avoid confusion.

### Compound Words in Property Names and Values

:star2: *Combine compound words in property names and values using camelCase.* :star2:

#### Guidelines

- Use camelCase for property names and values that are compound words (good examples: `signDisplay`, `"exceptZero"`).
- Avoid separating words with underscores, hyphens, or other delimiters (historical exceptions: "2-digit", "best fit").
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
- Avoid separating words with underscores, hyphens, or other delimiters (historical exceptions: "2-digit", "best fit").
- Avoid separating words with underscores, hyphens, or other delimiters (historical exceptions: `"2-digit"`, `"best fit"`).

- For values only, nonzero numbers should be expressed as digits (as in `"min2"`). Note that some terms, such as `"h23"`, originate from external specifications like UTS 35.

#### Rationale

- camelCase is a widely accepted convention in JavaScript and aligns with existing ECMA-402 practices.
Copy link
Contributor

Choose a reason for hiding this comment

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

Please dig up the thread in NumberFormat V3 where this was discussed, but we had a number of other reasons. One was that sometimes these strings end up as identifiers, and identifiers in JavaScript are camel case.

Copy link
Member Author

Choose a reason for hiding this comment

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

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah, I thought that was the original issue but I guess it is tc39/proposal-intl-displaynames#32

Actually, the style guide already says to use camel case here. There is a big section explaining the rationale. I think just refer to that previous section.

- Using digits for nonzero numbers in values ensures brevity and consistency with historical conventions.

### Open Question: `Style` vs. `Display` for High-Level Configuration Properties

There is an open question regarding the naming of high-level configuration properties: should we prefer to name them like `…Style` or `…Display`? They're both used relatively interchangably (e.g., `style`/`dateStyle`/`timeStyle` vs. `compactDisplay`/ `signDisplay`/`unitDisplay`). We must analyze this problem space in TG2 and come up with a convention.