diff --git a/index.bs b/index.bs index 29be67e4..c0dd0184 100644 --- a/index.bs +++ b/index.bs @@ -2205,7 +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. +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) @@ -3798,6 +3798,9 @@ 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 extremely common and easy to understand. +For example `UIEvent`, where "`UI`" stands for user interface.