From 3bcaa314b67b2b2a108512012b8eb964fc9e1291 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Fri, 3 Oct 2025 18:57:44 +0800 Subject: [PATCH 1/6] Avoid abbreviations for strings and enums --- index.bs | 1 + 1 file changed, 1 insertion(+) diff --git a/index.bs b/index.bs index 29be67e4..6bbd1df1 100644 --- a/index.bs +++ b/index.bs @@ -2206,6 +2206,7 @@ Use strings as the values for constants or sets of enumerated values. Strings make it easier for developers to inspect values and read code that uses those values. +As such, avoid abbreviations as they can make code harder to read. In JavaScript engines there is no performance benefit to using integers instead of strings. The values of a [WebIDL enum type](https://webidl.spec.whatwg.org/#idl-enums) From c517c9c35131d2718dc0558f6cfb150465b5d1b3 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Tue, 7 Oct 2025 16:50:35 +0800 Subject: [PATCH 2/6] Generally avoid abbreviations in naming --- index.bs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.bs b/index.bs index 6bbd1df1..ecf8a9c3 100644 --- a/index.bs +++ b/index.bs @@ -3799,6 +3799,8 @@ API naming *must* be done in easily readable US English. Keep in mind that most web developers aren't native English speakers. Whenever possible, names should be chosen that use common vocabulary a majority of English speakers are likely to understand when first encountering the name. +Abbreviations should be avoided, +except in cases where an abbreviation is canonicaland easier to understand.
From 49bcef7cc3d404e2bc192212b18f797363d5e4d7 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Tue, 7 Oct 2025 17:15:48 +0800 Subject: [PATCH 3/6] just point to naming is hard --- index.bs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/index.bs b/index.bs index ecf8a9c3..ea5afc98 100644 --- a/index.bs +++ b/index.bs @@ -2205,8 +2205,7 @@ is a request, rather than a guarantee. Use strings as the values for constants or sets of enumerated values. Strings make it easier for developers to inspect values -and read code that uses those values. -As such, avoid abbreviations as they can make code harder to read. +and read code that uses those values (see [[#naming-is-hard]]). In JavaScript engines there is no performance benefit to using integers instead of strings. The values of a [WebIDL enum type](https://webidl.spec.whatwg.org/#idl-enums) From d8ce305c38314ea06a2da5c3a6e19fe29de5ec48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 7 Oct 2025 17:19:52 +0800 Subject: [PATCH 4/6] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index ea5afc98..e7f66a9d 100644 --- a/index.bs +++ b/index.bs @@ -3799,7 +3799,7 @@ Keep in mind that most web developers aren't native English speakers. Whenever possible, names should be chosen that use common vocabulary a majority of English speakers are likely to understand when first encountering the name. Abbreviations should be avoided, -except in cases where an abbreviation is canonicaland easier to understand. +except in cases where an abbreviation is canonical and easier to understand.
From 4a70295ff3e103f43fef9e065db7d396cd12dcc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 7 Oct 2025 17:24:22 +0800 Subject: [PATCH 5/6] Update index.bs --- index.bs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index e7f66a9d..6d043fa9 100644 --- a/index.bs +++ b/index.bs @@ -3799,7 +3799,8 @@ Keep in mind that most web developers aren't native English speakers. Whenever possible, names should be chosen that use common vocabulary a majority of English speakers are likely to understand when first encountering the name. Abbreviations should be avoided, -except in cases where an abbreviation is canonical and easier to understand. +except in cases where an abbreviation is extremely common and easier to understand. +For example `UIEvent`, where "`UI`" stands for user interface.
From ca03ebf01973d455f10fa33ac2169c64a9f9cc40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Tue, 7 Oct 2025 17:24:50 +0800 Subject: [PATCH 6/6] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 6d043fa9..c0dd0184 100644 --- a/index.bs +++ b/index.bs @@ -3799,7 +3799,7 @@ Keep in mind that most web developers aren't native English speakers. Whenever possible, names should be chosen that use common vocabulary a majority of English speakers are likely to understand when first encountering the name. Abbreviations should be avoided, -except in cases where an abbreviation is extremely common and easier to understand. +except in cases where an abbreviation is extremely common and easy to understand. For example `UIEvent`, where "`UI`" stands for user interface.