From b2c19969a41af097ac2233009f0b2af69ea6aeed Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 4 Dec 2024 21:54:19 +1100 Subject: [PATCH] Correct bad advice on undefined conversion (#518) As noted in #437, simple advice to treat absence as equivalent to being passed `undefined` is a mistake. This advice only really applies to Boolean arguments. We discussed and concluded that string and number arguments have no sensible default that we could recommend. Booleans do. Closes #437. --- index.bs | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/index.bs b/index.bs index f8a6725b..1a59197a 100644 --- a/index.bs +++ b/index.bs @@ -1607,7 +1607,6 @@ element.scrollIntoView(false); See also: * Hall of API Shame: Boolean Trap. -* APIs that have boolean arguments defaulting to true * [[#optional-parameters]] * [[#naming-optional-parameters]] @@ -1622,15 +1621,16 @@ This defaults to `false`, meaning that the event should be dispatched to the listener in the bubbling phase by default. -Note: Exceptions have been made for legacy interoperability reasons -(such as {{XMLHttpRequest}}), -but this should be considered a design mistake rather than recommended practice. +For boolean arguments, +a default value of `false` +is strongly preferred. -The API must be designed so that if an argument is left out, -the default value used is the same as -converting {{undefined}} to the type of the argument. -For example, if a boolean argument isn't set, -it must default to false. +
+The third, optional argument to {{XMLHttpRequest}} +defaults to `true` as an exception to this rule. +This is for legacy interoperability reasons, +not as an example of good design. +
When deciding between different list data types for your API, unless otherwise required, use the following list types: @@ -1642,6 +1642,7 @@ unless otherwise required, use the following list types: See also: * [[#prefer-dictionaries]] +* APIs that have boolean arguments defaulting to true

Name optional arguments appropriately