From 1da4c4a28946f698526f24d46083736999ccfba5 Mon Sep 17 00:00:00 2001 From: Theresa O'Connor Date: Wed, 18 Mar 2020 10:29:27 -0700 Subject: [PATCH 1/4] Attempt to address some of the naming feedback in #132 and #149. --- index.bs | 54 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 39 insertions(+), 15 deletions(-) diff --git a/index.bs b/index.bs index 3dfd3eda..4c90f5b0 100644 --- a/index.bs +++ b/index.bs @@ -182,37 +182,61 @@ by showing how many sites are willing to ask for intrusive and unnecessary permi

Naming things

-Naming is hard! We would all like a silver-bullet for naming APIs... - Names take meaning from: * signposting (the name itself) * use (how people come to understand the name over time) * context (the object on the left-hand side, for example) -Consistency is a good principle that helps to create a platform that users can navigate intuitively -and by name association. +

Use common words

-Please consult widely on names in your APIs. +API naming *must* be done in easily readable US English. +Keep in mind that most web developers are not native English speakers. +Whenever possible, names should be chosen that use common vocabulary +non-native English speakers are likely to understand when first encountering the name. +Always value readability over brevity. + +

Use ASCII names -Names should adhere to the local language restrictions, for example CSS ident rules etc. +Names must adhere to the local language restrictions, for example CSS ident rules etc. and *should* be in the [ASCII range](https://infra.spec.whatwg.org/#ascii-code-point). +

Consultation

+ +Please consult widely on names in your APIs. + +

Future-proofing

+ +Naming should be generic and future-proof whenever possible. + +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. + +

Consistency

+Naming schemes should aim for consistency, to avoid confusion. + +Sets of related names should agree with each other in: + * part of speech - noun, verb, etc. + * negation, for example all of the names in a set should either describe what is allowed + or they should all describe what is denied + +
Boolean properties vs. + boolean-returning methods
+ Boolean properties, options, or API parameters which are asking a question about their argument *should not* be prefixed with is, while methods that serve the same purpose, given that it has no side effects, *should* be prefixed with is to be consistent with the rest of the platform. -The name should not be directly associated with a brand or specific revision of -the underlying technology whenever possible; technology becomes obsolete, but -since removing APIs from the web is difficult, naming should be generic and -future-proof whenever possible. - -

Use casing rules consistent with existing APIs

+
Use casing rules consistent with existing APIs
Although they haven't always been uniformly followed, through the history of web platform API design, the following rules have emerged: From 2f9ba01a03712b10e7ff69aea498c7fa00502cc5 Mon Sep 17 00:00:00 2001 From: Theresa O'Connor Date: Mon, 4 May 2020 14:30:59 -0700 Subject: [PATCH 2/4] Expand the naming consultation advice. --- index.bs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/index.bs b/index.bs index 4c90f5b0..23f8148d 100644 --- a/index.bs +++ b/index.bs @@ -211,6 +211,26 @@ and *should* be in the [ASCII range](https://infra.spec.whatwg.org/#ascii-code-p

Consultation

Please consult widely on names in your APIs. +You may find good names or inspiration in surprising places. +What are similar APIs named on other platforms, +or in popular libraries in various programming languages? +Ask end users and developers what they call +things that your API works with or manipulates. +Look at other web platform specifications, +and seek advice from others working in related areas of the platform. + +Pay particular attention to advice you receive +with clearly-stated rationale based on underlying principles. + +
+ +Tantek Çelik [extensively researched](https://tantek.com/2011/238/b1/many-ways-slice-url-name-pieces) +how to name the various pieces of a URL. +The editors of the [URL spec](https://url.spec.whatwg.org) +have relied on this research +when editing that document. [[URL]] + +

Future-proofing

From d59b3a767b35c5d2a4215f487e5e50ceb9906bdb Mon Sep 17 00:00:00 2001 From: Theresa O'Connor Date: Mon, 4 May 2020 14:42:10 -0700 Subject: [PATCH 3/4] Expand on readibility v. brevity. --- index.bs | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/index.bs b/index.bs index 23f8148d..3ebdb208 100644 --- a/index.bs +++ b/index.bs @@ -194,14 +194,33 @@ API naming *must* be done in easily readable US English. Keep in mind that most web developers are not native English speakers. Whenever possible, names should be chosen that use common vocabulary non-native English speakers are likely to understand when first encountering the name. -Always value readability over brevity. -

+ +For example `horizontalAlignment` is +a more English-readable name +than `alignmentHorizontal`. + + + +Value readability over brevity, +though always keep in mind that sometimes +the shorter name is the clearer one. +For instance, +it may be appropriate to use technical language or well-known terms of art +in the specification where the API is defined. -Note: It may be appropriate to use technical language or well-known terms of art -in the specification where the API is defined; -this principle applies only to the API names themselves. +

+ +For example, +the Fetch API's {{Body}} mixin's {{Body/json()}} method +is named for the kind of object it returns. +JSON is a well-known term of art +among web developers likely to use the Fetch API. +It would harm comprehension +to name this API less directly connected to its return type. [[FETCH]] + +

Use ASCII names

From da48077310051eea2e3a3e493f64d480aadab16a Mon Sep 17 00:00:00 2001 From: Theresa O'Connor Date: Mon, 4 May 2020 15:49:09 -0700 Subject: [PATCH 4/4] Add two future-proofing examples. --- index.bs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/index.bs b/index.bs index 3ebdb208..e947c9d6 100644 --- a/index.bs +++ b/index.bs @@ -259,6 +259,25 @@ 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. +
+ +The Remote Playback API was not named +after one of the pre-existing, proprietary systems it was inspired by +(such as Chromecast or AirPlay). +Instead, general terms that describe what the API does were chosen. [[REMOTE-PLAYBACK]] + +
+ +
+ +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]] + +
+

Consistency

Naming schemes should aim for consistency, to avoid confusion.