Skip to content

Commit

Permalink
Add normative 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 Jul 16, 2024
1 parent d2736cb commit 1f1f4a6
Showing 1 changed file with 27 additions and 0 deletions.
27 changes: 27 additions & 0 deletions normative-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,30 @@ For the purposes of this guideline `-0` is considered to be an integral number (
Some APIs intentionally round non-integral inputs, for example as an attempt to provide a best-effort behavior, rather than because the API fundamentally only makes sense with integers. This guideline does not apply to those cases.

NB: This convention is new as of 2024, and most earlier parts of the language do not follow it.

### Order of observable operations when processing arguments

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. If _a_ is not a Number, throw a **TypeError** exception.
> 1. Let _firstOperand_ be ℝ(_a_).
> 1. If _b_ is **undefined**, then
> 1. Let _secondOperand_ be 42.
> 1. Else,
> 1. If _b_ is not a Number, throw a **TypeError** exception.
> 1. Let _secondOperand_ be ℝ(_b_).
> 1. If abs(_firstOperand_ - _secondOperand_) > 10, throw a **RangeError** exception.
> 1. Return 𝔽(_firstOperand_ + _secondOperand_).
The first four steps process and validate each argument in order; Step 5 validates the other precondition that the numbers aren't too far apart; and Step 6 does the actual work.

NB: This convention is new as of 2022.
However, many parts of the language do already follow it.

0 comments on commit 1f1f4a6

Please sign in to comment.