Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

New principle: Return undefined from side-effect-causing functions. #500

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

New principle: Return undefined from side-effect-causing functions. #500

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f03cf4e
New principle: Return undefined from side-effect-causing functions. F…
hober Jul 15, 2024
05a8f15
Update index.bs
hober Jul 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ urlPrefix: https://w3c.github.io/geolocation-api/; spec: geolocation
url:#dom-geolocation-watchposition; type:method; for:Geolocation; text:watchPosition()
urlPrefix: https://html.spec.whatwg.org/multipage/; spec: HTML
url: system-state.html#dom-navigator-online; type: attribute; for: NavigatorOnline; text: onLine;
url: media.html#dom-media-play; type:method; for:HTMLMediaElement; text:play()
urlPrefix: https://w3c.github.io/remote-playback/; spec: REMOTE-PLAYBACK
url: #remoteplayback-interface; type:interface; text: RemotePlayback
url: #dfn-remote-playback-devices; type:dfn; text: remote playback device
Expand Down Expand Up @@ -1877,6 +1878,56 @@ If the bytes in the buffer have a natural intepretation
as one of the other TypedArray types, provide that instead.
For example, if the bytes represent Float32 values, use a {{Float32Array}}.

<h3 id=void-functions>Return <code>undefined</code> from side-effect-causing functions</h3>
<!-- Guidance about return values of (conceptually) void functions #286 -->
<!-- https://github.com/w3ctag/design-principles/issues/286 -->

When the purpose of a function
is to cause side effects
and not to compute a value,
the function should be specified
to return {{undefined}}.

Sites are unlikely
to come to depend on
such a return value,
which makes it easier
to change the function
to return a meaningful value
in the future
should a use case for one be discovered.

<div class="example">

{{HTMLMediaElement}}’s {{HTMLMediaElement/play()}} method
was originally defined to return {{undefined}},
since its purpose was
to change the state
of the media element.

Requests to play media
can fail
in a number of ways,
so {{HTMLMediaElement/play()}} was [changed](https://github.com/whatwg/html/issues/505)
to return a {{Promise}}.
If the <abbr>API</abbr>
had originally been defined
to return something other than {{undefined}}
(for example,
if it had been defined
to return the media element,
a popular pattern
in “chaining” <abbr>API</abbr>s),
it would not have been backwards compatible
to enhance the usability of this <abbr>API</abbr>
in this manner.

</div>

See also:

* [Command–query separation on Wikipedia](https://en.wikipedia.org/wiki/Command–query_separation)

<h2 id="event-design">Event Design</h2>

<h3 id="one-time-events">Use promises for one time events</h3>
Expand Down