Editorial Conventions

TODO: add a symbol marking things that are enforced by ecmarkup?

General Principles

TODO

• use consistent phrasing as much as possible
• without loss of readability, minimise the number of foundational concepts in the spec
• consider how each change will affect the full variety of potential spec consumers
• so that fragment links continue to bring the visitor to the most relevant position in the current document, preserve old IDs (using the oldids attribute if necessary)
• AO summaries are normative, so every claim they contain should be correct without further qualification. However, they can (and are expected to) omit some details so as to be more easily understandable. Additionally, AO summaries may provide relevant context that makes no claims about the behaviour of the AO.

Ecma TOOLS-011

Ecma maintains a "standard for standards", TOOLS-011, available on the Ecma documents server, which outlines many rules for presentation and text conventions for Ecma documents. Make a best effort to follow these rules, with the following exceptions:

• 6.2.14: Decimal fractions and large numbers

  We use a . (FULL STOP) for the decimal mark and a , (COMMA) for digit grouping, as this is the common convention for other web technology specifications, despite the broad recommendation across standards-setting organisations.

• 6.2.15: Names of graphic characters and control functions

  We use Unicode for representation of text, not any of the listed Ecma standards for text encoding. Because of that, we follow Unicode conventions for character naming and code point references.

Phrasing Conventions

• use % notation to refer to intrinsic objects, not "the initial value of"
• test for presence of a field using _record_ has a/an [[X]] field, not _record_.[[X]] is present
• use a/an/a new for creating and referencing values with identity; use the for referencing values without identity
• in an SDO invocation, use "the" before the SDO name iff all of the following hold:
  • the SDO name is a noun phrase
  • the SDO does not return a completion record
  • the SDO invocation does not occur within an AO invocation
• a grammar production "matches" some source text, and source text "is matched by" some grammar production; never the other way around
• don't unnecessarily qualify object types with the word "object"; _x_ is an Array, not _x_ is an Array object, with the following exceptions:
  • when referring to an exotic object in a context which emphasizes its exotic nature, use an X exotic object
  • "Set object", to distinguish from the spec-internal type of the same name
  • "Error object" and variants, to make it clear it's talking about a value rather than an exceptional condition
  • "RegExp object", to distinguish it from RegExp literals
  • "Proxy object" because it reads a little better
• don't use increment/decrement, increase/decrease, or add/subtract; instead, use the regular facilities, as in set _x_ to _x_ + 1
• append or prepend a value to a List using append _x_ to _list or prepend _x_ to _list, respectively
• to test whether a List is empty, use _list_ is empty or _list_ is not empty
• to access the first element of a List whose length is known to be 1, use the sole element of _list_
• to create an untagged union of types,
  • If all types are singletons, use A (for 1 type), either A or B (for 2), or one of A, B, or C (for 3+)
  • Else, use an A (for 1 type), either an A or a B (for 2), or either an A, a B, or a C (for 3+) where all types with >1 inhabitant are listed before all singletons
• prefer the empty String over *""*

Constructing Lists

Outside of AO argument lists, construct Lists using:

• the list-concatenation of some other Lists; see list-concatenation
• a List whose elements are (2+),
• a List whose sole element is (1),
• a new empty List (0)

Inside AO argument lists, construct Lists using double angle brackets («»).

Comparisons

• use =, ≠, <, ≤, >, and ≥ for mathematical value and bigint comparisons (except in asserts); prefer = over ≠
• use is, is not, <, ≤, >, and ≥ for number comparisons
• use SameValue(..., ...) is *true* for equality comparison of symbols (except well-known) / objects / unknown ECMAScript language values
• use is and is not for equality comparison of all other values, including booleans, strings, well-known symbols, null, undefined, enums, etc; don't use "is different from" or "is the same as"
• prefer "if a is either b or c" over "if a is b or a is c"; use "one of" in place of "either" when more than 2 options
• prefer "if a is c and b is c" over "if a and b are both c"
• presence in a List is tested with _list_ contains _element_ or _list_ does not contain _element_, not _element_ is an element of _list_ or _element_ is in _list_
• prefer "whose _ is _" over "whose _ is that of _"
• when performing an equality comparison between an alias and a constant, the alias should be on the LHS and the constant should be on the RHS

Algorithm Conventions

• don't say the value of _a_; just use _a_
• prefer "if a or b" over "if a or if b"; prefer "if a and b" over "if a and if b"
• in algorithm steps, each alias should only be introduced (such as with "Let") at most once for any possible trace through the algorithm
• in an if/else or if/else-if/else, either all branches are given substeps or all branches are collapsed
• invoke AOs that return ~unused~ only from the top level of a step, using the verb "perform"
• prefer spec enums over sentinel values like -1
• do not re-use the same spec enum value in unrelated places (excepting ~unused~)
• do not make dynamic references to AOs or alias AOs; only refer to AOs in calling position
• do not mutate Completion Records
• when returning a constant after comparing it to an alias, return the constant, not the alias: If _x_ is *null*, return *null*.
• prefer "is a throw completion", "is a normal completion", etc. shorthands over comparing against the [[Type]] slot of a Completion Record
• lead with validation steps that early exit, then follow the happy path
• prefer descriptive alias names over single-letter or abbreviated names, especially for longer-lived aliases
• algorithm steps should do only 1 thing, don't try to do in 1 step what could be done in 2 or more

Text Conventions

NOTE: ecmarkup enforces many typographic conventions, most of which are not listed here

• include Oxford commas
• denote all characters literally, using HTML entities only as required by HTML syntax
• use this spacing for Records: { [[key1]]: value1, [[key2]]: value2 }
• use this spacing for Lists: « value1, value2 »
• always indicate the sign of floating point zeroes using either +0_𝔽 or -0_𝔽; never use 0_𝔽