Skip to content

Commit

Permalink
Correct bad advice on undefined conversion (#518)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
martinthomson authored Dec 4, 2024
1 parent d0137b5 commit b2c1996
Showing 1 changed file with 10 additions and 9 deletions.
19 changes: 10 additions & 9 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -1607,7 +1607,6 @@ element.scrollIntoView(false);
See also:

* <a href="https://ariya.io/2011/08/hall-of-api-shame-boolean-trap">Hall of API Shame: Boolean Trap</a>.
* <a href="https://lists.w3.org/Archives/Public/public-script-coord/2013OctDec/0302.html">APIs that have boolean arguments defaulting to true</a>
* [[#optional-parameters]]
* [[#naming-optional-parameters]]

Expand All @@ -1622,15 +1621,16 @@ This defaults to `false`, meaning that
the event should be dispatched to the listener in the bubbling phase by default.
</div>

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.
<div class="example">
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.
</div>

When deciding between different list data types for your API,
unless otherwise required, use the following list types:
Expand All @@ -1642,6 +1642,7 @@ unless otherwise required, use the following list types:
See also:

* [[#prefer-dictionaries]]
* <a href="https://lists.w3.org/Archives/Public/public-script-coord/2013OctDec/0302.html">APIs that have boolean arguments defaulting to true</a>

<h3 id="naming-optional-parameters">Name optional arguments appropriately</h3>

Expand Down

0 comments on commit b2c1996

Please sign in to comment.