You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>Naming should be generic and future-proof whenever possible.</p>
3827
-
<p>The name should not be directly associated with a brand or specific revision of
3828
-
the underlying technology whenever possible; technology becomes obsolete, and
3829
-
removing APIs from the web is difficult.</p>
3825
+
<h3class="heading settled" data-level="12.4" id="naming-future-proofing"><spanclass="secno">12.4. </span><spanclass="content">Use names that describe a purpose</span><aclass="self-link" href="#naming-future-proofing"></a></h3>
3826
+
<p>Name things for what they do, not how they do it.</p>
3827
+
<p>Names that reflect the purpose of their subject
3828
+
are more likely to be future-proof. <ahref="#removing-features">Removing APIs from the web is difficult</a>,
3829
+
so names need to outlast details.</p>
3830
+
<p>In particular,
3831
+
names should avoid the use of
3832
+
code names,
3833
+
branding,
3834
+
or details of the technology used to implement capabilities.
3835
+
These can become obsolete
3836
+
and might need to be replaced in the future.</p>
3830
3837
<divclass="example" id="example-fd8a196a">
3831
3838
<aclass="self-link" href="#example-fd8a196a"></a>
3832
3839
<p>The Remote Playback API was not named
3833
3840
after one of the pre-existing, proprietary systems it was inspired by
3834
3841
(such as Chromecast or AirPlay).
3835
3842
Instead, general terms that describe what the API does were chosen. <adata-link-type="biblio" href="#biblio-remote-playback" title="Remote Playback API">[REMOTE-PLAYBACK]</a></p>
3836
3843
</div>
3837
-
<divclass="example" id="example-c1204afc">
3838
-
<aclass="self-link" href="#example-c1204afc"></a>
3839
-
<p>The <code>keydown</code> and <code>keyup</code><codeclass="idl"><adata-link-type="idl" href="https://w3c.github.io/uievents/#keyboardevent" id="ref-for-keyboardevent①">KeyboardEvent</a></code>s were not named
3840
-
for the specific hardware bus that keyboards used at the time.
3841
-
Instead, generic names were chosen
3842
-
that are as applicable to today’s Bluetooth and USB keyboards
3843
-
as they were to PS/2 and ADB keyboards back then. <adata-link-type="biblio" href="#biblio-uievents" title="UI Events">[UIEVENTS]</a></p>
3844
+
<divclass="example" id="example-4a43ecba">
3845
+
<aclass="self-link" href="#example-4a43ecba"></a>
3846
+
<p>The WebTransport API enables the networking capabilities provided by the QUIC protocol.
3847
+
However, the name reflects the more general purpose of transporting data. <adata-link-type="biblio" href="#biblio-webtransport" title="WebTransport">[WebTransport]</a><adata-link-type="biblio" href="#biblio-rfc9000" title="QUIC: A UDP-Based Multiplexed and Secure Transport">[RFC9000]</a></p>
3844
3848
</div>
3845
3849
<h3class="heading settled" data-level="12.5" id="naming-consistency"><spanclass="secno">12.5. </span><spanclass="content">Name things consistently</span><aclass="self-link" href="#naming-consistency"></a></h3>
3846
3850
Naming schemes should aim for consistency, to avoid confusion.
<dd>M. Nottingham. <ahref="https://www.rfc-editor.org/rfc/rfc8890"><cite>The Internet is for End Users</cite></a>. August 2020. Informational. URL: <ahref="https://www.rfc-editor.org/rfc/rfc8890">https://www.rfc-editor.org/rfc/rfc8890</a>
4611
+
<dtid="biblio-rfc9000">[RFC9000]
4612
+
<dd>J. Iyengar, Ed.; M. Thomson, Ed.. <ahref="https://www.rfc-editor.org/rfc/rfc9000"><cite>QUIC: A UDP-Based Multiplexed and Secure Transport</cite></a>. May 2021. Proposed Standard. URL: <ahref="https://www.rfc-editor.org/rfc/rfc9000">https://www.rfc-editor.org/rfc/rfc9000</a>
4607
4613
<dtid="biblio-rfc9110">[RFC9110]
4608
4614
<dd>R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. <ahref="https://httpwg.org/specs/rfc9110.html"><cite>HTTP Semantics</cite></a>. June 2022. Internet Standard. URL: <ahref="https://httpwg.org/specs/rfc9110.html">https://httpwg.org/specs/rfc9110.html</a>
<dd>Cullen Jennings; et al. <ahref="https://w3c.github.io/webrtc-pc/"><cite>WebRTC: Real-Time Communication in Browsers</cite></a>. URL: <ahref="https://w3c.github.io/webrtc-pc/">https://w3c.github.io/webrtc-pc/</a>
4627
+
<dtid="biblio-webtransport">[WebTransport]
4628
+
<dd>Nidhi Jaju; Victor Vasiliev. <ahref="https://w3c.github.io/webtransport/"><cite>WebTransport</cite></a>. URL: <ahref="https://w3c.github.io/webtransport/">https://w3c.github.io/webtransport/</a>
"1812300f": {"dfnID":"1812300f","dfnText":"dialog","external":true,"refSections":[{"refs":[{"id":"ref-for-the-dialog-element"}],"title":"3.1. Re-use HTML attribute names (only) for similar functionality"}],"url":"https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element"},
4874
4882
"19065ec8": {"dfnID":"19065ec8","dfnText":"abort()","external":true,"refSections":[{"refs":[{"id":"ref-for-dom-abortcontroller-abort"}],"title":"6.11. Cancel asynchronous APIs/operations using AbortSignal"},{"refs":[{"id":"ref-for-dom-abortcontroller-abort\u2460"}],"title":"7.6. Guard against potential recursion"}],"url":"https://dom.spec.whatwg.org/#dom-abortcontroller-abort"},
4875
4883
"1bb59bab": {"dfnID":"1bb59bab","dfnText":"AudioWorklet","external":true,"refSections":[{"refs":[{"id":"ref-for-AudioWorklet"}],"title":"10.2.1. Some APIs should only be exposed to dedicated workers"}],"url":"https://webaudio.github.io/web-audio-api/#AudioWorklet"},
4876
-
"1fc098b2": {"dfnID":"1fc098b2","dfnText":"KeyboardEvent","external":true,"refSections":[{"refs":[{"id":"ref-for-keyboardevent"}],"title":"2.15. Build complex types by composing simpler types"},{"refs":[{"id":"ref-for-keyboardevent\u2460"}],"title":"12.4. Use future-proof names"}],"url":"https://w3c.github.io/uievents/#keyboardevent"},
4884
+
"1fc098b2": {"dfnID":"1fc098b2","dfnText":"KeyboardEvent","external":true,"refSections":[{"refs":[{"id":"ref-for-keyboardevent"}],"title":"2.15. Build complex types by composing simpler types"}],"url":"https://w3c.github.io/uievents/#keyboardevent"},
4877
4885
"2039631f": {"dfnID":"2039631f","dfnText":"namespace","external":true,"refSections":[{"refs":[{"id":"ref-for-dfn-namespace"},{"id":"ref-for-dfn-namespace\u2460"}],"title":"6.8. Classes should have constructors when possible"}],"url":"https://webidl.spec.whatwg.org/#dfn-namespace"},
4878
4886
"21ec9802": {"dfnID":"21ec9802","dfnText":"inherit","external":true,"refSections":[{"refs":[{"id":"ref-for-css-inheritance"}],"title":"4.3. Choose the computed value type based on how the property should inherit"}],"url":"https://drafts.csswg.org/css-cascade-5/#css-inheritance"},
4879
4887
"2296404c": {"dfnID":"2296404c","dfnText":"signal abort","external":true,"refSections":[{"refs":[{"id":"ref-for-abortcontroller-signal-abort"},{"id":"ref-for-abortcontroller-signal-abort\u2460"},{"id":"ref-for-abortcontroller-signal-abort\u2461"},{"id":"ref-for-abortcontroller-signal-abort\u2462"},{"id":"ref-for-abortcontroller-signal-abort\u2463"},{"id":"ref-for-abortcontroller-signal-abort\u2464"},{"id":"ref-for-abortcontroller-signal-abort\u2465"}],"title":"7.6. Guard against potential recursion"}],"url":"https://dom.spec.whatwg.org/#abortcontroller-signal-abort"},
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments