Add 'Choose the Appropriate WebIDL Construct for Data and Behavior' #567
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -1524,6 +1524,132 @@ the interaction with garbage collection. | |||
|
|
|||
| <h2 id="api-surface">JavaScript API Surface Concerns</h2> | |||
|
|
|||
| <h3>Choose the Appropriate WebIDL Construct for Data and Behavior (Dictionaries, Interfaces, and Namespaces)</h3> | |||
|
|
|||
| Web APIs commonly pass around data and functionality using WebIDL. As a specification author, decide carefully whether | |||
There was a problem hiding this comment.
We generally go with something more direct for this first paragraph/sentence of each principle.
| } | ||
| ``` | ||
|
|
||
| If the interface can holds data that is useful when serialized (e.g., `GeolocationPosition`), consider adding a `toJSON()` default method. Alternatively, if it holds binary data, one can add .toBlob() an so on. |
There was a problem hiding this comment.
Is this toJSON() thing something that belongs here? Or is it a distraction?
Comment on lines
+1624
to
+1629
| If warrented by the use cases, give the interface a constructor. Be mindful to not just add a constructor if a class has no state. Doing so is considered by practice by effectively creaeting a fake class. | ||
| (see `DOMParser` or `DOMImplementation` as bad examples). |
There was a problem hiding this comment.
Is this a different principle again?
|
|
||
| Each construct has its own pros and cons, discussed below. | ||
|
|
||
| <h4>Use Dictionaries for “Configuration” or “Input-Only” Data</h4> |
There was a problem hiding this comment.
Later sections use something like this:
<h4 id="static-objects" class="no-num no-toc">Static objects</h4>Consider following that example.
|
Is this meant to close #11? |
Co-authored-by: Martin Thomson <[email protected]>
jyasskin
force-pushed
the
interfaces-dicts-namespaces
branch
from
f982070 to
d27fcae
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Initial text to picking the right thing...
Preview | Diff