-
Notifications
You must be signed in to change notification settings - Fork 113
Meta: Add naming conventions section in style guide #996
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.
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
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -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/* | ||||||
|
|
||||||
|
|
@@ -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. | ||||||
| - 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"). | ||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
| - 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. | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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.
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is this it? tc39/proposal-intl-numberformat-v3#9
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).