From 3bcaa314b67b2b2a108512012b8eb964fc9e1291 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Fri, 3 Oct 2025 18:57:44 +0800 Subject: [PATCH 01/10] 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 02/10] 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 03/10] 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 04/10] 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 05/10] 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 06/10] 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.
From 026f6f0c4095ed86dcb155a198e812483f6da85a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 16 Oct 2025 09:58:11 +0800 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Jeffrey Yasskin --- index.bs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index c0dd0184..2a8accfd 100644 --- a/index.bs +++ b/index.bs @@ -2203,9 +2203,10 @@ is a request, rather than a guarantee.

Use strings for constants and enums

Use strings as the values for constants or sets of enumerated values. +See [[#naming-is-hard]] when choosing strings. Strings make it easier for developers to inspect values -and read code that uses those values (see [[#naming-is-hard]]). +and read code that uses those values. 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) @@ -3798,7 +3799,7 @@ 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, +Avoid abbreviations, except in cases where an abbreviation is extremely common and easy to understand. For example `UIEvent`, where "`UI`" stands for user interface. From 330d865d72c8f8bc4b66c1a2a90f2db3f767db47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 16 Oct 2025 09:58:57 +0800 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Jeffrey Yasskin --- index.bs | 1 + 1 file changed, 1 insertion(+) diff --git a/index.bs b/index.bs index 2a8accfd..6ac5a04d 100644 --- a/index.bs +++ b/index.bs @@ -2204,6 +2204,7 @@ is a request, rather than a guarantee. Use strings as the values for constants or sets of enumerated values. See [[#naming-is-hard]] when choosing strings. +See [[#naming-is-hard]] when choosing strings. Strings make it easier for developers to inspect values and read code that uses those values. From e84bf3ac65fdaa43ae89b0b19e76da1d08a8b01f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Thu, 16 Oct 2025 09:59:19 +0800 Subject: [PATCH 09/10] Update index.bs --- index.bs | 1 - 1 file changed, 1 deletion(-) diff --git a/index.bs b/index.bs index 6ac5a04d..2a8accfd 100644 --- a/index.bs +++ b/index.bs @@ -2204,7 +2204,6 @@ is a request, rather than a guarantee. Use strings as the values for constants or sets of enumerated values. See [[#naming-is-hard]] when choosing strings. -See [[#naming-is-hard]] when choosing strings. Strings make it easier for developers to inspect values and read code that uses those values. From 2c165551b73a29a63925bd13222306f0c9b2a8e7 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Tue, 21 Oct 2025 12:50:44 +0800 Subject: [PATCH 10/10] Move text per review feedback --- index.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 4641c42d..c6edefb6 100644 --- a/index.bs +++ b/index.bs @@ -3826,10 +3826,7 @@ Names take meaning from: 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. -Avoid abbreviations, -except in cases where an abbreviation is extremely common and easy to understand. -For example `UIEvent`, where "`UI`" stands for user interface. +a majority of English speakers are likely to understand when first encountering the name.
@@ -3840,6 +3837,9 @@ than `cardinality`.
Value readability over brevity. +Avoid abbreviations, +except in cases where an abbreviation is extremely common and easy to understand. +For example `UIEvent`, where "`UI`" stands for user interface. Keep in mind, however, that the shorter name is often the clearer one. For instance,