From e2fc038e48e7dc2d7d79c818be5fd6915c0e9def Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Thu, 25 Aug 2022 17:00:29 -0700 Subject: [PATCH] Add spec convention about order of operations Triggered by the discussion in https://github.com/tc39/proposal-temporal/pull/2377#discussion_r948263720 Arguments should consistently be processed in order. --- spec-conventions.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/spec-conventions.md b/spec-conventions.md index 74cc7b2..76ff8d1 100644 --- a/spec-conventions.md +++ b/spec-conventions.md @@ -15,4 +15,32 @@ ## Implementations of functions and methods +### Order of observable operations + +When writing the algorithm steps for the implementation of a JS built-in +function or method, this order should be followed: + +1. If applicable, process and validate the receiver. +1. Process and validate each argument, in order. +1. Perform validation of any other preconditions, if any. +1. Perform the actual work of the function. + +Validating the arguments includes type checking, but also unobservable things +like supplying default arguments. +So, for a fictitious `addTwoNumbersThatArentTooFarApart(a, b = 42)` function, +the algorithm steps could look like this: + +> 1. Let _firstOperand_ be ℝ(? ToNumber(_a_)). +> 1. If _b_ is **undefined**, then +> 1. Let _secondOperand_ be 42. +> 1. Else, +> 1. Let _secondOperand_ be ℝ(? ToNumber(_b_)). +> 1. If _firstOperand_ - _secondOperand_ > 10, then +> 1. Throw a **RangeError** exception. +> 1. Return 𝔽(_firstOperand_ + _secondOperand_). + +The first three steps process and validate each argument in order; Step 4 +validates the other precondition that the numbers aren't too far apart; and +Step 5 does the actual work. + ## Normative or editorial?