Editorial: rename single-letter and initial-capital aliases

[michaelficarra]

Fixes #3119. Generated summary of renames:

Before	After	Sections
A	array	Array AOs, Array constructor/statics, Array.prototype methods, Internal methods, RS: IteratorBindingInitialization, RS: IteratorDestructuringAssignmentEvaluation, RegExp AOs, RegExp.prototype methods, TypedArray AOs
A	caseClauses	RS: CaseBlockEvaluation
A	charSet	CharacterComplement, CharacterRange, CharacterRangeOrUnion, CharacterSetMatcher, MaybeSimpleCaseFolding, RS: CompileAtom, RS: CompileCharacterClass, RS: CompileToCharSet
A	deletedArray	Array.prototype methods
A	newArray	Array.prototype methods
A	resultArray	TypedArray.prototype methods
a	integerPart	Number.prototype methods
AR	agentRecord	Agent/module AOs, Atomics AOs, Atomics methods, Buffer/DataView AOs, CopyDataBlockBytes, SharedArrayBuffer.prototype methods
Attributes	attributes	Object statics
B	blockCompletion	RS: CatchClauseEvaluation
B	blockResult	RS: Evaluation
B	firstOctet	Decode
B	otherSet	CharacterRange, CharacterRangeOrUnion, MaybeSimpleCaseFolding, RS: CompileToCharSet
B	secondCaseClauses	RS: CaseBlockEvaluation
b	fractionalPart	Number.prototype methods
BC	boundTarget	Ordinary object internals
Body	body	Internal methods
C	activeFunc	AsyncFunction, Generator types
C	catchResult	RS: Evaluation
C	clause	RS: CaseBlockEvaluation
C	codeUnit	Annex B: escape, Annex B: unescape, Decode, Encode
C	completion	GeneratorPrototype methods, Iterator helper prototypes
C	constructor	%TypedArray% statics, Array AOs, Array constructor/statics, Function constructor, JSON AOs, Object utility AOs, Promise AOs, Promise statics, Promise.prototype methods, RS: CaseClauseIsSelected, UnicodeEscape
C	remainingSet	CharacterRangeOrUnion, RS: CompileToCharSet
C	speciesConstructor	RegExp.prototype methods
C	stmtCompletion	RS: Evaluation
C	value	Ordinary object internals, Promise AOs
c	continue	EmptyMatcher, MatchSequence, MatchTwoAlternatives, RS: CompileAssertion, RS: CompileSubpattern
c	exponentSign	Number.prototype methods
Current	current	Property Descriptor AOs
D	deletable	Environment Record methods, Environment Records, Global declaration AOs
D	desc	Ordinary object internals
D	eventB	Memory model constraints, Memory model relations
D	rangeSet	RS: CompileToCharSet
d	exponentDigits	Number.prototype methods
DclRec	declarativeRecord	Environment Record methods, Global declaration AOs
Desc	desc	Array AOs, Internal methods, Invariants, Ordinary object internals, Property Descriptor AOs, Proxy internal methods, ValidateAndApplyPropertyDescriptor
E	e	CreateListIteratorRecord
E	event	Memory model AOs
E	eventA	Memory model constraints, Memory model relations
E	item	Array.prototype methods
E	outerEnv	Environment AOs
e	exponent	Number.prototype methods
e	matchEnd	RegExp.prototype methods
Extensible	extensible	Property Descriptor AOs
F	activeFunc	Promise AOs, Proxy internal methods, SS: ShallowestContainedJSONValue
F	boundFunc	Function.prototype
F	closure	RS: InstantiateAsyncFunctionObject, RS: InstantiateAsyncGeneratorFunctionObject, RS: InstantiateGeneratorFunctionObject, RS: InstantiateOrdinaryFunctionObject
F	constructor	Construct
F	constructorFunction	RS: ClassDefinitionEvaluation
F	eventC	Memory model relations
F	fieldName	ValidateAndApplyPropertyDescriptor
F	finallyResult	RS: Evaluation
F	flags	RegExp AOs, RegExp constructor/statics, RegExp.prototype methods
F	func	Call, Function AOs, Function constructor, Function.prototype, Internal methods, eval AOs
F	funcName	Declaration instantiation, eval AOs
F	funcObj	RS: Evaluation
F	obj	Environment AOs, Function AOs, Internal methods, Ordinary object internals
F	thisValue	Function.prototype
f	fractionCount	Number.prototype methods
G	generator	RS: EvaluateGeneratorBody
G	obj	Environment AOs
i	captureIndex	RegExp.prototype methods
i	searchStart	String.prototype methods
i	writeIndex	Array.prototype methods
Input	input	BackreferenceMatcher, CharacterSetMatcher, IsWordChar, Notation, RS: CompileAssertion, RS: CompileAtom, RS: CompilePattern, RS: CompileSubpattern
InputLength	inputLength	BackreferenceMatcher, CharacterSetMatcher, IsWordChar, RS: CompileAssertion
j	matchIndex	String.prototype methods
K	keys	JSON AOs
k	digitCount	Number.prototype methods
k	sourceIndex	Array.prototype methods
L	length	Function.prototype
L	lowercaseString	String.prototype methods
L	waiters	Atomics AOs
LeftFirst	leftFirst	IsLessThan
M	map	Map.prototype methods, get Map.prototype.size
M	module	Environment Record methods, ModuleNamespaceCreate
M	targetModule	Environment Record methods
M	weakMap	WeakMap.prototype methods
m	digitString	Number.prototype methods
m	significand	Number.prototype methods
N	n	The Syntactic Grammar
N	name	Environment Record methods, Environment Records, Global declaration AOs
n	captureIndex	RegExp.prototype methods
n	intSignificand	Number.prototype methods
n	intValue	Number.prototype methods
n	matchCount	RegExp.prototype methods
n	nextIndex	Array.prototype methods
n	resultIndex	Array.prototype methods
n	startIndex	Array.prototype methods
N2	n2	Environment Record methods
O	iteratorObj	ArrayIterator prototype, RegExpStringIterator prototype
O	obj	Array.prototype methods, ArrayBuffer.prototype methods, AsyncFromSyncIterator prototype, Boolean, DataView constructor, DataView.prototype methods, Date constructor/statics, Date.prototype methods, Environment AOs, Error types, ForInIterator prototype, Internal methods, IsValidIntegerIndex, Iterator helper prototypes, Iterator methods, JSON methods, Number constructor/statics, Object integrity AOs, Object setup AOs, Object statics, Object utility AOs, Object.prototype.__proto__, Ordinary object internals, Private field AOs, Property access AOs, Proxy internal methods, RegExp constructor/statics, RegExp.prototype methods, Set constructor, Set.prototype methods, SharedArrayBuffer.prototype methods, String.prototype methods, Type conversion/utility AOs, TypedArray AOs, TypedArray constructors, TypedArray.prototype methods, Uint8Array methods, ValidateAndApplyPropertyDescriptor, WrapForValidIteratorPrototype
O	thisValue	Object statics, Object.prototype.__proto__, String AOs, String statics, String.prototype methods
O	value	Object utility AOs, Ordinary object internals, RequireInternalSlot, Type conversion/utility AOs
Obj	obj	Property Descriptor AOs
ObjRec	objectRecord	Environment Record methods, Global declaration AOs
Octets	octets	Decode, Encode
P	p	The Syntactic Grammar
P	parameterString	Function constructor
P	pattern	RegExp AOs, RegExp.prototype methods
P	patternSource	RegExp constructor/statics
P	propertyKey	Array AOs, Array.prototype methods, Internal methods, Invariants, Invoke, JSON AOs, Object statics, Object utility AOs, Ordinary object internals, Private field AOs, Property access AOs, Proxy internal methods, RS: PropertyBindingInitialization, Set constructor, String AOs, ValidateAndApplyPropertyDescriptor
P	propertyName	RS: PropertyDestructuringAssignmentEvaluation
P	proto	Ordinary object internals
P	proxy	ProxyCreate
p	lastMatchEnd	RegExp.prototype methods
p	matchPosition	String.prototype methods
p	precisionCount	Number.prototype methods
p	propertyKey	SetterThatIgnoresPrototypeProperties
ParameterList	parameterList	Internal methods
Pi	propertyKey	Array.prototype methods
Pk	propertyKey	%TypedArray% statics, Array AOs, Array constructor/statics, Array.prototype methods, TypedArray AOs, TypedArray.prototype methods
prop	propertyKey	GetTemplateObject, JSON AOs, JSON methods
Properties	properties	Object statics, Object utility AOs
PropertyDescriptor	propertyDescriptor	Object internal method conventions
PropertyList	propertyList	JSON methods
propKey	propertyKey	RS: DefineMethod, RS: MethodDefinitionEvaluation, RS: PropertyDefinitionEvaluation
q	searchIndex	RegExp.prototype methods
R	completion	RS: CaseBlockEvaluation
R	obj	RegExp AOs
R	r	Spec type definitions
R	radixMV	Global functions
R	readEvent	Memory model AOs, Memory model constraints, Memory model relations, reads-bytes-from
R	regexp	RegExp AOs, RegExp.prototype methods, RegExpStringIterator prototype
R	result	Annex B: escape, Annex B: unescape, Array.prototype methods, Decode, Encode, RS: Evaluation, String statics, String.prototype methods, TypedArray.prototype methods, reads-bytes-from
R	separatorStr	String.prototype methods
R	thisValue	RegExp AOs, RegExp.prototype methods
r	readIndex	Array.prototype methods
realmC	constructorRealm	Array AOs
Receiver	receiver	Internal methods, Invariants, Object internal method conventions, Ordinary object internals
ReplacerFunction	replacerFunction	JSON methods
rer	regexpRecord	AllCharacters, BackreferenceMatcher, Canonicalize, CharacterComplement, CharacterRangeOrUnion, CharacterSetMatcher, HasEitherUnicodeFlag, IsWordChar, MaybeSimpleCaseFolding, Notation, RS: CompileAssertion, RS: CompileAtom, RS: CompileCharacterClass, RS: CompileClassSetString, RS: CompilePattern, RS: CompileSubpattern, RS: CompileToCharSet, RegExp AOs, UnicodeMatchProperty, UpdateModifiers, WordCharacters
rx	regexp	RegExp.prototype methods, String.prototype methods
S	charSet	CharacterComplement, RS: CompileToCharSet
S	elementStr	Array.prototype methods, TypedArray.prototype methods
S	escapedPattern	RegExp AOs
S	eventA	Memory model relations
S	isStrict	Environment Record methods, Environment Records
S	objectSet	WeakRef liveness
S	segment	Decode
S	set	Set.prototype methods, get Set.prototype.size
S	species	Object utility AOs
S	str	Annex B: CreateHTML, Annex B: escape, Internal methods, RegExp AOs, RegExp constructor/statics, RegExp.prototype methods, RegExpStringIterator prototype, String AOs, String.prototype methods, The String Type
S	thisValue	String.prototype methods
S	trimmedString	Global functions
S	values	Array AOs
S	waiters	Atomics methods
S	weakSet	WeakSet.prototype methods
s	sign	Number.prototype methods
SortCompare	sortCompare	Array AOs, Array.prototype methods, TypedArray.prototype methods
Strict	isStrict	Internal methods
Sw	eventB	Memory model relations
T	substring	RegExp.prototype methods, String.prototype methods
T	trimmedString	String AOs
Target	target	Function.prototype
Throw	throw	Set constructor
V	codePoint	Decode
V	iterationResult	ForIn/Of evaluation, RS: DoWhileLoopEvaluation, RS: ForLoopEvaluation, RS: WhileLoopEvaluation
V	obj	Object utility AOs
V	proto	Internal methods, Ordinary object internals
V	referenceRecord	Property access AOs, Reference AOs
V	resultValue	RS: CaseBlockEvaluation
V	thisValue	Call
V	value	Annex B: CreateHTML, Environment Record methods, Environment Records, Function.prototype, Global declaration AOs, HostCallJobCallback, InstanceofOperator, Internal methods, Invariants, Invoke, Memory model constraints, Object statics, Object utility AOs, Ordinary object internals, Property access AOs, Proxy internal methods, Reference AOs, Reflect methods, Set constructor
v	value	SetterThatIgnoresPrototypeProperties
W	newValue	Environment AOs
W	referenceRecord	Reference AOs
W	value	Reference AOs
W	waiterRecord	Atomics methods
W	writeEvent	Memory model AOs, Memory model constraints, Memory model relations, reads-bytes-from
WL	waiterList	Atomics AOs, Atomics methods, EnqueueAtomicsWaitAsyncTimeoutJob, EnqueueResolveInAgentJob
Ws	writes	Memory model AOs, Memory model constraints, reads-bytes-from
X	ownProperty	Ordinary object internals
x	matchState	EmptyMatcher, MatchSequence, MatchTwoAlternatives, RS: CompileAssertion, RS: CompileSubpattern
x	numberValue	Number.prototype methods
x	source	eval, eval AOs
Z	numberString	Global functions
z	matchResult	RegExp.prototype methods
z	zeroPad	Number.prototype methods

Disclaimer: I used AI in the process of creating this PR.

[github-actions]

The rendered spec preview for this PR is available as a single page at https://tc39.es/ecma262/pr/3789 and as multiple pages at https://tc39.es/ecma262/pr/3789/multipage .

[linusg]

big fan except for these:

• prop, propKey, propertyKey - not sure why you turned P into three variants?
• pk - should be whatever the above gets unified to
• rx - awfully shortened to avoid conflicts with regexp, a clear sign that something went wrong naming wise

I also don't quite like obj, funcObj, desc, and str (why numberString and not numberStr then?) but won't block those.

[michaelficarra]

@linusg We're already fairly inconsistent with how short we shorten our aliases. I'm happy to make your suggested changes, but if we want to actually be consistent with how we abbreviate words for alias names (and probably AO names?), that'd be another whole effort in itself.

[linusg]

Naming is hard 🙂

Happy with a follow-up but would love to see the two letter ones disappear now.

[michaelficarra]

This reads really weird, but it's just because of existing type confusion in the prose. We should follow up to make the prose work better.

[nicolo-ribaudo]

Also in the other internal methods

[ljharb]

the one-letter variables read much more nicely to me uppercase than lowercase, fwiw.

[michaelficarra]

Okay I've scrolled through the diff and fixed all the errors I could find. I also updated the summary, which turned out to be a very effective way to find erroneous renames ("why is the S alias being renamed to set in the String section?", "Why are the module examples being renamed?", etc.). As with any change this big, there's bound to be some overly-zealous find-replaces that escaped their intended region, so additional eyes are appreciated.

[linusg]

Did a full manual pass over the diff.

• PutValue now has two identically named params, should be (referenceRecord, value) like in InitializeReferencedBinding
• OrdinaryHasInstance, SetImmutablePrototype: Same as above
• deletable and isStrict are much better than D and S, but I would either give both or neither the is prefix - especially as they both appear in env AOs
  • slight preference for dropping it, IsCompatiblePropertyDescriptor uses extensible
• N -> name so N2 -> name2, not n2 (could obviously be improved but let's at least avoid the single letter name) - GetBindingValue, CreateImportBinding
• NewObjectEnvironment: newValue -> isWithEnvironment
• There is both [[SetPrototypeOf]] ( value ) and [[SetPrototypeOf]] ( proto ) (all used to be V before, proto seems fine but let's be consistent)
• RequireInternalSlot: value -> object, more common if the first step is type validation I think
• PrepareForOrdinaryCall, OrdinaryCallBindThis, OrdinaryCallEvaluateBody (and some more, search for obj (an ECMAScript function object) and obj (a function object)): obj -> func to match [[Call]] and [[Construct]], MakeConstructor, and some others. Used to be F.
• Three instances of For each FunctionDeclaration f should probably be updated too
• TypedArrayCreate: array -> typedArray (though a lot of TA AOs changed O to obj - either seems better than array here)
  • %TypedArray%.prototype.map, slice, toReversed, toSorted, with: same for resultArray
  • Optional: obj -> ta / typedArray, proxy, arrayBuffer etc in methods and related AOs (all used to be O)
  • We already do this for Map, Set, WeakMap, WeakSet
• ModuleNamespaceCreate: M -> module conflicts with param of the same name
• %ForInIteratorPrototype%.next ( ): obj -> iter to avoid Let object be obj.[[Object]].
• SwitchStatement : switch ( Expression ) CaseBlock uses result, Catch : catch ( CatchParameter ) Block uses blockCompletion, TryStatement : try Block Catch and friends use blockResult / catchResult - could be a bit more consistent IMO
• Lots of Let obj be ? ToObject(obj) conflicts in Object static methods, should be Set or different name
• String.prototype.search and friends now have to use Set regexp to instead of Let regexp, but a better option is to rename the parameter to regexpOrPattern IMO
• Most of the RegExp machinery still uses one and two char names but I'm fine with keeping these for a follow-up (mostly because I don't like reading the regexp stuff 😛)
  • e.g. CharacterSetMatcher: x, c, e, f, ch, cc, y
• RegExpInitialize, RegExp ctor: redeclares params
• RegExp.prototype [ %Symbol.replace% ]: n -> captureIndex is a bad choice for 1-based indexing IMO
  • "More generally, the captureIndexth capture (the characters captured by the captureIndexth set of capturing parentheses) is at captures[captureIndex - 1]." is confusing
• get RegExp.prototype.source, get RegExp.prototype.sticky, etc: thisValue -> regexp would be clearer IMO
• CreateRegExpStringIterator: obj -> regexp
  • %RegExpStringIteratorPrototype%.next ( ) calls it regexp too when reading the [[IteratingRegExp]] slot
• IsConcatSpreadable: value -> obj (if we agree that naming args after their expected and not actual type is the way to go)
• Set.prototype.difference, intersection, isDisjointFrom, isSubsetOf, isSupersetOf, symmetricDifference, union: obj -> set for consistency with the rest
• Atomics.notify: better name for c needed
• InternalizeJSONProperty: If there exists an element e of entryRecords such that e.[[Key]] - e -> entry or similar
• QuoteJSONString, UnicodeEscape faulty C -> constructor rename (but it's funny)
  • CaseClauseIsSelected: Same here (constructor -> caseClause or similar), I missed this earlier
• NewPromiseCapability: value -> constructor to match Promise.all and friends
• %GeneratorPrototype%.return and friends: g -> gen/generator (or obj if need be)
• CreateHTML: value conflicts param, escapedV should be updated to mirror the rename
• RegExp.prototype.compile: params redeclared

[michaelficarra]

@linusg Thank you for the review. Comments addressed.

[linusg]

I looked at the additional commits and they seem good, but I'd like to do another pass after someone else has reviewed this before approving. There's also a conflict 🙂

[michaelficarra]

With a PR this large and spread out, it's going to be hard to keep it conflict-free. So @tc39/ecma262-editors let's try to get it reviewed soon if we can.

[nicolo-ribaudo]

Note: I only reviewed your changes and code around them. I didn't go through untouched text yet.

[nicolo-ribaudo]

This section is still full of pretty useless names, some of which are one letter some of which are two letters but they are just the initial of two words put together (_m1_, _m2_, _d_, _c_, _q_, _xe_, _ye_, _cv_ ...).

I don't know much about our regexp spec to have suggestions, maybe leave it as a follow-up since they are a lot.

[michaelficarra]

I think I'd prefer to leave the matcher AOs to a follow-up. The goal of this proposal is not to completely eliminate abbreviated aliases, but to reduce their usage where it would help with readability. And I don't think replacing m1/m2 with something longer would help. Maybe some of the others would, though.

[nicolo-ribaudo]

These one-line vars are good.

[michaelficarra]

I'm assuming you mean one-letter? If so, I agree, which is why I've left them.

[nicolo-ribaudo]

There are a bunch of loops across the spec where we keep "For each element e of". Pointing it out but I don't have a better suggestion, maybe 1 letter is fine since it's just immediately used in the line after.

[nicolo-ribaudo]

• MakeMatchIndicesIndexPairArray: s -> name (i and n in there are fine)
• CompareArrayElements, CompareTypedArrayElements: v -> result / comparisonResult (x and y in there are fine)
• AddEntriesFromIterable: k, v -> key, value?
• Map.groupBy/AddValueToKeyedGroup: g -> group
• Map.prototype.clear -> p -> pair / entry? Also in other map and set methods. In CreateMapIterator it's called e.
• A bunch of stuff in DoWait, where cannot guess what those 1-letter names are short for
• AtomicReadModifyWrite, Atomics.store: v -> coercedValue / numericValue / typedValue?
• JSON.stringify: v -> value, or propertyValue (for symmetry with propertyKey)
• IsPromise: x -> value. I'd say let's just keep "x" (and "y") as a valid name for math-y stuff
• Promise.reject: r -> reason
• Promise.prototype.finally, Proxy.revocable: p. I don't have a great suggestion because promise/proxy are already used for something else.
• Date.prototype.setYear: d/t/y/u -> day/time/year/utcTimestamp. Maybe also rename yyyy.

There are also still many places where we use _v_ but it could be _value_. Don't just find-and-replace because _v_ is also correctly used for the regexp flag.

[nicolo-ribaudo]

• FunctionDeclarationInstantiation, BlockDeclarationInstantiation, GlobalDeclarationInstantiation: d / f -> decl / fnDecl
• CreateMappedArgumentsObject: g / p -> getter / setter
• sec-module-namespace-exotic-objects-get-p-receiver: m -> module (or just inline it)
• sec-relational-operators-runtime-semantics-evaluation: r -> result / comparisonResult; s / sl -> statementsListResult / statementResult?
• %ForInIteratorPrototype%.next: r -> key / nextRemainingKey
• ClassDefinitionEvaluation: e -> element

There is a whole bunch of _m_s for "module" in the module stuff. Maybe it's fine, it's only used very locally when there is already a _module_ variable in scope.

[jmdyck]

There are problems with renaming single-letter aliases to have the same name as an alias that already exists in the same algorithm.

[michaelficarra]

Thanks for the review @nicolo-ribaudo. I pushed up a bunch of commits addressing your feedback.

[nicolo-ribaudo]

This is now good enough for me :)

There are potential follow-up opportunities but let's merge this first.

[michaelficarra]

@linusg Did you want to do another review, or should I mark this one as ready to merge?

[linusg]

i'll do another review today.

[linusg]

• PrivateElementFind, PrivateFieldAdd, PrivateGet, PrivateSet: propertyKey -> privateName (used to be P) - there's precedent in https://tc39.es/ecma262/#sec-relational-operators-runtime-semantics-evaluation
• CreateListIteratorRecord: e -> value (used to be E)
• SuperCall evaluation: having func and funcObj is not great (one is this, the other one the super constructor)
• PropertyDestructuringAssignmentEvaluation, IteratorDestructuringAssignmentEvaluation: v -> value
• RegExp: pattern -> regexpOrPattern would resolve some awkwardness like we did in the String.prototype methods, having pattern and patternSource is weird
• IsPromise: promise -> arg/argument/value like in most of https://tc39.es/ecma262/#sec-testing-and-comparison-operations. I think speculative naming is good when the first step is validation and the expectation is that a certain object type is passed, but here it's completely neutral.

There's some other stuff that I don't like but I'll submit that as follow-ups.

[linusg]

🚢

[ljharb]

@michaelficarra this PR has 91 commits. should they just all be squashed into one?

[michaelficarra]

yeah I think so

changes addressed