Avoid abbreviations for strings and enums #600
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR updates documentation to provide clearer guidance on string and enum naming conventions. The change adds explicit advice to avoid abbreviations when using strings as constants or enumerated values, emphasizing code readability.
- Added guidance to avoid abbreviations in string constants and enums
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
index.bs
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
Can we not just cite https://w3ctag.github.io/design-principles/#naming-is-hard ?
If that doesn't mention abbreviation, then it can be updated to do that.
|
|
||
| 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]]). |
There was a problem hiding this comment.
I think this fits better in the first paragraph:
| and read code that uses those values (see [[#naming-is-hard]]). | |
| and read code that uses those values. |
|
|
||
| <h3 id="string-constants">Use strings for constants and enums</h3> | ||
|
|
||
| Use strings as the values for constants or sets of enumerated values. |
There was a problem hiding this comment.
| 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. |
| 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, |
There was a problem hiding this comment.
https://github.com/w3ctag/process/blob/main/style-guide.md#use-the-active-voice
| Abbreviations should be avoided, | |
| Avoid abbreviations, |
| 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. |
There was a problem hiding this comment.
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.
This pull request makes a minor update to the documentation for using strings as constant values. The change clarifies that abbreviations should be avoided, as they can make code harder to read.
Closes #599
Preview | Diff