Skip to content

Conversation

@marcoscaceres
Copy link
Contributor

@marcoscaceres marcoscaceres commented Oct 3, 2025

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

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

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

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
Comment on lines 3801 to 3803
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.
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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think Intl namespace was a mistake from ECMA was a mistake. Would other folks here agree?

marcoscaceres and others added 2 commits October 16, 2025 09:58
Copy link
Contributor

@jyasskin jyasskin left a comment

Choose a reason for hiding this comment

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

This would fit better into the "Value readability over brevity." paragraph and the example that follows it, but this is good enough for me.

@martinthomson
Copy link
Contributor

I agree with Jeffrey. This is more naturally under "brevity".

@marcoscaceres marcoscaceres enabled auto-merge (squash) October 21, 2025 04:51
@marcoscaceres marcoscaceres merged commit 9fc15ba into main Oct 21, 2025
1 check passed
@marcoscaceres marcoscaceres deleted the abbrs branch October 21, 2025 04:52
github-actions bot added a commit that referenced this pull request Oct 21, 2025
SHA: 9fc15ba
Reason: push, by marcoscaceres

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

avoid abbreviations

3 participants