Skip to content

Commit

Permalink
Add spec convention about order of operations
Browse files Browse the repository at this point in the history
Triggered by the discussion in tc39/proposal-temporal#2377 (comment)
Arguments should consistently be processed in order.
  • Loading branch information
ptomato committed Feb 13, 2023
1 parent ab51256 commit e2fc038
Showing 1 changed file with 28 additions and 0 deletions.
28 changes: 28 additions & 0 deletions spec-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?

0 comments on commit e2fc038

Please sign in to comment.