Skip to content

Avoid abbreviations for strings and enums #600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Avoid abbreviations for strings and enums #600

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3bcaa31
Avoid abbreviations for strings and enums
marcoscaceres Oct 3, 2025
c517c9c
Generally avoid abbreviations in naming
marcoscaceres Oct 7, 2025
49bcef7
just point to naming is hard
marcoscaceres Oct 7, 2025
d8ce305
Update index.bs
marcoscaceres Oct 7, 2025
4a70295
Update index.bs
marcoscaceres Oct 7, 2025
ca03ebf
Update index.bs
marcoscaceres Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2205,7 +2205,7 @@ is a request, rather than a guarantee.
Use strings as the values for constants or sets of enumerated values.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Use strings as the values for constants or sets of enumerated values.
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.
and read code that uses those values (see [[#naming-is-hard]]).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this fits better in the first paragraph:

Suggested change
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)
Expand Down Expand Up @@ -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,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/w3ctag/process/blob/main/style-guide.md#use-the-active-voice

Suggested change
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.
Comment on lines +3801 to +3803
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an example of "Value readability over brevity" in the next non-example paragraph. How about

Value readability over brevity.
Often this means to avoid abbreviations.
Keep in mind, however, that

You could add the "UI" example into that example. It might be good to also have an example of when the abbreviation was a mistake.


<div class="example">

Expand Down