Skip to content

Commit

Permalink
Attempt to split attribute by type (#485)
Browse files Browse the repository at this point in the history
* Attempt to split attribute by type

HTML vs. IDL

* Accessors

Co-authored-by: Lea Verou <[email protected]>

* -n

* spacing

---------

Co-authored-by: Lea Verou <[email protected]>
  • Loading branch information
martinthomson and LeaVerou authored Jun 3, 2024
1 parent 7ed4eb0 commit c3eaec9
Showing 1 changed file with 17 additions and 18 deletions.
35 changes: 17 additions & 18 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -891,12 +891,12 @@ to reduce such dilemmas in the future.

This section details design principles for features which are exposed via HTML.

<h3 id="attribute-reuse">Re-use attribute names (only) for similar functionality</h3>
<h3 id="attribute-reuse">Re-use HTML attribute names (only) for similar functionality</h3>

If you are adding a feature that is specified through an HTML attribute,
check if there is an existing attribute name on another element
that specifies similar functionality.
Re-using an existing attribute name means authors can utilize existing knowledge,
Re-using an existing HTML attribute name means authors can utilize existing knowledge,
maintains [consistency](#consistency) across the language,
and keeps its vocabulary small.

Expand All @@ -913,7 +913,7 @@ and keeps its vocabulary small.
and then re-used by <{dialog}>.
</div>

If you do re-use an existing attribute,
If you do re-use an existing HTML attribute,
try to keep its syntax as close as possible to the syntax of the existing attribute.

<div class="example">
Expand All @@ -931,7 +931,7 @@ try to keep its syntax as close as possible to the syntax of the existing attrib
</div>

The inverse also applies:
do **not** re-use an existing attribute name if
do **not** re-use an existing HTML attribute name if
the functionality you are adding is **not** similar to that of the existing attribute.

<div class="example">
Expand Down Expand Up @@ -1462,37 +1462,36 @@ See also:

* [[#attributes-like-data]]

<h3 id="attributes-vs-methods">Use attributes or methods appropriately</h3>
<h3 id="attributes-vs-methods">Accessors should behave like properties, not methods</h3>

Sometimes it is unclear
whether to use an attribute or a method.
IDL attributes that describe object properties or getters produce information about the state of an object.

- Attribute getters must not have any (observable) side effects.
- A getter must not have any (observable) side effects.
If you have expected side effects, use a method.

- Attribute getters should not throw exceptions.
- Getters should not throw exceptions.
Getters should [behave like regular data properties](#attributes-like-data), and regular data properties do not throw exceptions when read. Furthermore, invalid state should generally be avoided by rejecting *writes*, not when data is *read*.
Updating existing getters to throw exceptions should be avoided as existing API users may enumerate or wrap the API and not expect the new exception, breaking backwards compatibility.

- Attribute getters should not perform any blocking operations.
- Getters should not perform any blocking operations.
If a getter requires performing a blocking operation,
it should be a method.

- If the underlying object has not changed,
attribute getters should return
getters should return
the same object each time it is called.
This means `obj.attribute === obj.attribute` must always hold.
Returning a new value from an attribute getter
This means `obj.property === obj.property` must always hold.
Returning a new value from an getter
each time is not allowed.
If this does not hold, the getter should be a method.

Note: An antipattern example of a blocking operation is with getters like offsetTop performing layout.
Note: An antipattern example of a blocking operation is with getters like `offsetTop` performing layout.

For attributes, whenever possible,
When defining IDL attributes, whenever possible,
preserve values given to the setter
for return from the getter.
That is, given `obj.attribute = x`,
a subsequent `obj.attribute === x` should be true.
That is, given `obj.property = x`,
a subsequent `obj.property === x` should be true.
(This will not always be the case,
e.g., if a normalization or type conversion step is necessary,
but should be held as a goal for normal code paths.)
Expand All @@ -1502,7 +1501,7 @@ This means:

- If live, then return the same object each time,
until a state change requires a different object to be returned.
This can be returned from either an attribute or a method.
This can be returned from either a property, getter, or method.

- If static, then return a new object each time.
In which case, this should be be a method.
Expand Down

0 comments on commit c3eaec9

Please sign in to comment.