From f03cf4e3aa6ad44b0647af3405b842e588efe52d Mon Sep 17 00:00:00 2001
From: Theresa O'Connor <eoconnor@apple.com>
Date: Mon, 15 Jul 2024 11:41:16 -0700
Subject: [PATCH 1/2] New principle: Return undefined from side-effect-causing
 functions. Fixes #286.

---
 index.bs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/index.bs b/index.bs
index a55b526..49013fc 100644
--- a/index.bs
+++ b/index.bs
@@ -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
@@ -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](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>

From 05a8f157333b59cc793f62e657401a7a1308a510 Mon Sep 17 00:00:00 2001
From: Theresa O'Connor <hober@apple.com>
Date: Tue, 16 Jul 2024 09:25:08 -0700
Subject: [PATCH 2/2] Update index.bs

Co-authored-by: Domenic Denicola <d@domenic.me>
---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 49013fc..82d8b9e 100644
--- a/index.bs
+++ b/index.bs
@@ -1926,7 +1926,7 @@ in this manner.
 
 See also:
 
-* [Command–query_separation](https://en.wikipedia.org/wiki/Command–query_separation)
+* [Command–query separation on Wikipedia](https://en.wikipedia.org/wiki/Command–query_separation)
 
 <h2 id="event-design">Event Design</h2>