Editorial: Insert "the" before SDO-names

[jmdyck]

E.g., change:

1. Return the BoundNames of |Foo|.

to:

1. Return BoundNames of |Foo|.

---

This PR is divided into 4 commits, depending on:

• whether the occurrence is in pseudocode or prose, and
• whether it's at the start or middle of a sentence ("The" vs "the").

since those are factors that might conceivably affect how you feel about the removal.

For the origin of this PR, see the discussion at #3210 (comment) and following (re the second "the").

---

Personally, I've got mixed feelings about this PR: I like the consistification, but I think the status quo is slightly easier to read. One possibility would be to include "The" in the name of some SDOs, e.g.

1. Return TheBoundNames of |Foo|.

Another possibility would be use a more punctuation-based syntax for SDO invocations (e.g.,

1. Return |Foo|.BoundNames().

from https://github.com/bterlson/ecma262/pull/3/files). It isn't necessarily easier to read, but the syntax signals that it should be read more like a programming language (as with AO invocations).

[michaelficarra]

This is great!

[michaelficarra]

At the editor call, we decided we'd rather add a metadata field to SDOs so we can choose on a per-SDO basis whether the invocation should use "the". This will also allow tooling to ensure that the proper calling convention is used (and potentially automatically fix it). We'll then review each SDO and decide wether is should have "the" or not.

[jmdyck]

We'll then review each SDO and decide wether is should have "the" or not.

Okay, here's some data for your review.

In practice, an SDO name is either:

• a predicate (like IsSimpleParameterList or Contains),
• an imperative (like CompileAtom or InstantiateFunctionObject), or
• a noun phrase (like BoundNames or StringValue) or an abbreviation of a noun phrase (MV, SV, TV, TRV).

In the first two cases, it wouldn't make grammatical sense to put "the" before the SDO name (and the spec doesn't). So I'll only consider the last case, where it's at least grammatically plausible. But in the subcase that the SDO returns a completion record, its invocations will typically be prefixed with ? or Completion(, which (I think) primes the reader to expect what follows to not be English-like text. So you probably don't want "the" in those cases, and in fact, in all such cases the spec doesn't use "the".

That leaves SDOs with noun-phrase names that don't return a completion record. In the current spec, there are 45 such, and most of them (26) have at least one invocation with "the". Here's a list of them. Each line starts with the number of invocations (in the status quo) that have "the", and the number that don't. I also included each SDO's return-type (and sorted by that), in case that affects your decision as to whether the SDO should have "the" or not.

  0   1  ClassStaticBlockDefinitionEvaluation : a ClassStaticBlockDefinition Record
  0   3  ExportEntries                        : a List of ExportEntry Records
  2   2  ExportEntriesForModule               : a List of ExportEntry Records
  0   3  ImportEntries                        : a List of ImportEntry Records
  2   5  ImportEntriesForModule               : a List of ImportEntry Records
  2   3  TopLevelLexicallyScopedDeclarations  : a List of Parse Nodes
  3   2  ReferencedBindings                   : a List of Parse Nodes
  3   5  TopLevelVarScopedDeclarations        : a List of Parse Nodes
 10   8  LexicallyScopedDeclarations          : a List of Parse Nodes
 18  23  VarScopedDeclarations                : a List of Parse Nodes
  0   2  PropertyNameList                     : a List of Strings
  1   4  TopLevelLexicallyDeclaredNames       : a List of Strings
  1   7  PrivateBoundIdentifiers              : a List of Strings
  2   6  ModuleRequests                       : a List of Strings
  2   6  TopLevelVarDeclaredNames             : a List of Strings
  4   2  ExportedBindings                     : a List of Strings
  6   2  ExportedNames                        : a List of Strings
 28  19  VarDeclaredNames                     : a List of Strings
 33   9  LexicallyDeclaredNames               : a List of Strings
 87  33  BoundNames                           : a List of Strings
  0   2  IdentifierCodePoints                 : a List of code points
  0   2  RegExpIdentifierCodePoints           : a List of code points
  0   6  TemplateStrings                      : a List of either Strings or *undefined*
  0   2  PrototypePropertyNameList            : a List of property keys
  0   2  NonConstructorElements               : a List of |ClassElement| Parse Nodes
  0   4  StringNumericValue                   : a Number
  3   0  NumericValue                         : a Number or a BigInt
  0   4  DeclarationPart                      : a Parse Node
  3   1  CapturingGroupName                   : a String
 12   0  SV                                   : a String
 27   0  TRV                                  : a String
 44  33  StringValue                          : a String
 11   0  TV                                   : a String or *undefined*
  0  16  PropName                             : a String or ~empty~
  0   4  IdentifierCodePoint                  : a code point
  0   4  RegExpIdentifierCodePoint            : a code point
 81  11  MV                                   : a mathematical value
 18   0  CharacterValue                       : a non-negative integer
  2   0  CapturingGroupNumber                 : a positive integer
  0   3  ConstructorMethod                    : a |ClassElement| Parse Node or ~empty~
  1   3  ExpectedArgumentCount                : an integer
  0   2  BodyText                             : source text
  0   2  FlagText                             : source text
  0   4  ClassElementKind                     : ~constructor-method~, ~non-constructor-method~, or ~empty~
  0   8  AssignmentTargetType                 : ~simple~ or ~invalid~

[michaelficarra]

@bakkot Would invocations of one of these SDOs as a parameter of an AO still follow the "the" rule we define for it, or will we make an exception for that form?

[bakkot]

I'm inclined to make an exception for invocations of SDOs which are parameters of AOs or preceded by ? or !.

[jmdyck]

I'm inclined to make an exception for invocations of SDOs which are parameters of AOs

I think there's only one such case using "the" in the status quo:

It is a Syntax Error if IsStringWellFormedUnicode(the SV of |StringLiteral|) is false.

(So in the eventual version of this PR, there might be just that one "the" removed, and lots added.)

[jmdyck]

I've added a fixup to implement the following convention, so you can decide if that's what you want.

In an SDO-invocation, use "the" before the SDO name iff:

• the SDO name is a noun phrase,
• the SDO does not return a completion record, and
• the SDO-invocation does not occur within an AO-invocation.

[michaelficarra]

@jmdyck @bakkot What about cases like this? https://github.com/tc39/ecma262/pull/3307/files#diff-181371b08d71216599b0acccbaabd03c306da6de142ea6275c2135810999805aR20513

[jmdyck]

For a case like

1. Let _rval_ be ? NamedEvaluation of |AssignmentExpression|
    with argument StringValue of |LeftHandSideExpression|.

I'd be inclined to introduce an alias for the argument:

1. Let _foo_ be StringValue of |LeftHandSideExpression|.
1. Let _rval_ be ? NamedEvaluation of |AssignmentExpression|
    with argument _foo_.

(whether or not there's a "the" before the SDO names).

[bakkot]

Looks great.

[syg]

lgtm!

[michaelficarra]

LGTM. We should go through active open PRs and update them so they don't re-introduce inconsistencies while we wait for tooling to get updated.

[jmdyck]

(force-pushed to squash to one commit)