search

w3ctag / design-principles

A small-but-growing set of design principles collected by the TAG while reviewing specifications
https://w3ctag.github.io/design-principles
160 stars 44 forks source link

New principle: Document whether to add things to Document, Navigator, Window, or SomeOtherInterface #448

Open jyasskin opened 1 year ago

jyasskin commented 1 year ago

API designers often wonder how to namespace their new thing, and I don't think we have any existing guidance. #426 has some argument for and against using Window, but I think the principle should be broader than that. Some considerations:

Navigator "represent[s] the identity and state of the user agent", so it should hold objects that tend to be the same across different documents.

Document and Window are nearly equivalent, but adding things to Window means developers can use them without an object prefix, and they also risk colliding with things developers defined. Maybe we should say that infrequent use argues to put things on Document?

SomeOtherInterface.Thing and SomeOtherInterfaceThing are also nearly equivalent, as discussed in #426.

I'm sure other folks can think of more considerations. The more we can give these decisions a technical basis, the less likely they are to turn into prolonged bikeshedding discussions.

bathos commented 1 year ago

It may be worth noting that, ahead of considerations of semantic appropriateness, the lifecycles & relationships of candidate interfaces can impact whether they’re viable options. For example, the Window’s associated CustomElementRegistry couldn’t have belonged to the Document instead — though the conditions where this both occurs and is observed are uncommon, a Window’s associated Document can change one time (the registry could not have similarly changed underfoot soundly).

(I suppose a Document member could have steps like “return the associated Window’s associated Foo” to get around that, but personally I wouldn’t expect non-DOM/non-DOM-related specs to want to extend Document much anyway?)

LeaVerou commented 1 year ago

Completely agree about documenting guidance about this. Another consideration is whether the API in question may ever be useful in non-browser runtimes, we don't want to e.g. hang something on Navigator that may eventually become useful in Node and have to define a new API for it.