New principle: Guidance on options dictionaries and default values

[LeaVerou]

This came out of this Twitter thread which started from my observation that in Intl.Collator, the numeric option is false by default, which is rarely what you need.

Currently the only guidance we have wrt options dictionaries is this:

• 6.5. Make method arguments optional if possible
• 6.6. Name optional arguments appropriately

Which basically tell API designers to:

• make parameters optional if there is a "reasonable" default value (with no guidance about what may constitute "reasonable")
• name boolean parameters in such a way so that false is the default
• avoid negatives (because then optionName: false becomes a confusing double negative).

There's also a naming principle about preferring common words for names, though nothing about avoiding overly long names.

All good goals, but I think what a "reasonable" default is needs to be more explicitly defined (and needs to take into account % of use cases that would have needed to specify that value), and having reasonable defaults should be weighed more highly than all of the above, when there's no way to satisfy them all. If a boolean parameter is designed in such a way that false is the default, and the name is positive, but it needs to be specified in nearly every API invocation because this default actually only works for edge cases, that's not a great API IMO.

[LeaVerou]

From today's breakout:

• Between "name positively" and "false should be the default", we think the latter may be slightly more important
• Common cases should influence default values, maybe add note to relevant rule?

Will discuss again in plenary.

[annevk]

If all callers want numeric it should indeed have been disableNumeric. I think the principle there is that the majority of callers shouldn't have to pass an optional argument. (Though this cannot be an absolute.)

[LeaVerou]

I think the principle there is that the majority of callers shouldn't have to pass an optional argument.

I really like this wording!

(Though this cannot be an absolute.)

CSS.registerProperty() comes to mind, where you have to pass in inherits: true all the time, because the common case is less performant, so the API designers wanted this to be an explicit opt-in (I have my doubts about whether that was a good idea, but it is what it is).

[bakkot]

One of those docs says

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.

and I think that's basically wrong? A string-taking API should not be required to use the default value "undefined", which is what you get when converting undefined to a string (unless this document is using "converting" in an unusual way, i.e. not just '' + undefined). Similarly, NaN is almost never the right default for a Number-taking API, and 0 is only sometimes a reasonable default for an integer-taking API, which are what you get when converting undefined to a Number or integer in JS.

Rather, the way I'd put it is that an explicit undefined should be treated exactly the same as an option being absent¹. And, in addition, false should be the default for boolean parameters.

(That rule appears to have been introducing in #228.)

---

I agree with the OP that "reasonable defaults should be weighed more highly than all of the above". Not sure it's going to be possible to be any more precise about what "reasonable" means, though. It's not just a matter of which use case is more common - for example, if there's a potentially destructive API, I would want the default to be non-destructive even if in practice the destructive one comes up more. We could maybe collect some heuristics, though.

Footnotes

1. except in the (very rare) cases where undefined is a coherent value to use - for example, in JS the cause parameter in error constructors can take any JS value, including undefined, so that's one of the very rare cases which breaks this rule. ↩

[LeaVerou]

@bakkot Nice catch (wrt the sentence about undefined)! Could you file a new issue about this so we can track it fixing it separately?

[bakkot]

Opened #437.