From 7611b686a90dfa5736163a92fd1bb5c5b4669879 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 30 Jan 2025 15:39:25 +1100 Subject: [PATCH] Use names that describe purpose I found that I needed to redo the whole section here. Changing the focus seemed better than adding text. This is more text, but not a lot more. Future-proofing is one motivation, but it's not the real motivation for these recommendations. I also found the key event example to be spectacularly non-compelling. It even made me think that it is almost a bad example. Key events can be synthesized by speech recognition tools in some cases. To that end, I chose an example that I'm more familiar with. Closes #507. --- index.bs | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/index.bs b/index.bs index 6224fb9e..3b672973 100644 --- a/index.bs +++ b/index.bs @@ -3728,13 +3728,22 @@ such as an author or user, use the generic pronoun "they", "their", etc. For example, "A user may wish to adjust their preferences". -

Use future-proof names

+

Use names that describe a purpose

-Naming should be generic and future-proof whenever possible. +Name things for what they do, not how they do it. -The name should not be directly associated with a brand or specific revision of -the underlying technology whenever possible; technology becomes obsolete, and -removing APIs from the web is difficult. +Names that reflect the purpose of their subject +are more likely to be future-proof. +[[#removing-features|Removing APIs from the web is difficult]], +so names need to outlast details. + +In particular, +names should avoid the use of +code names, +branding, +or details of the technology used to implement capabilities. +These can become obsolete +and might need to be replaced in the future.
@@ -3747,11 +3756,9 @@ Instead, general terms that describe what the API does were chosen. [[REMOTE-PLA
-The `keydown` and `keyup` {{KeyboardEvent}}s were not named -for the specific hardware bus that keyboards used at the time. -Instead, generic names were chosen -that are as applicable to today's Bluetooth and USB keyboards -as they were to PS/2 and ADB keyboards back then. [[UIEVENTS]] +The WebTransport API enables the networking capabilities provided by the QUIC protocol. +However, the name reflects the more general purpose of transporting data. +[[WebTransport]][[RFC9000]]