Editorial: consistently abbreviate terms used in aliases#3837
Open
michaelficarra wants to merge 69 commits intomainfrom
Open
Editorial: consistently abbreviate terms used in aliases#3837michaelficarra wants to merge 69 commits intomainfrom
michaelficarra wants to merge 69 commits intomainfrom
Conversation
|
The rendered spec preview for this PR is available as a single page at https://tc39.es/ecma262/pr/3837 and as multiple pages at https://tc39.es/ecma262/pr/3837/multipage . |
linusg
reviewed
Apr 25, 2026
Member
linusg
left a comment
linusg
left a comment
There was a problem hiding this comment.
I think this goes into an entirely wrong direction; names should only be shortened if the short form is more common or more readable.
Member
Author
|
Sorry, I think my summary may have caused confusion because it didn't include all the short names that were being used for each of those names, so it looks like I'm only adding abbreviations. Here's a better summary of my intent with this PR: Abbreviate, but consistently
Don't abbreviate
If you think any of these are in the wrong section, let me know and I'll update the PR. I'm thinking maybe |
Member
Author
|
Okay I went through very thoroughly and (aside from the regexp section) I think I've covered all abbreviations I'm going to be able to find. You can generate the table of renames in this PR using the script in this gist: https://gist.github.com/michaelficarra/275a2b78d9ac5dcf75671fce849f0df4. Here's the output as of the most recent commit: renamed aliases table
I also added some entries to the two lists above related to the recent commits. |
Member
|
I mentioned it yesterday, but I forgot to write a comment. I'd prefer if we did not shorten |
Member
Author
|
I pushed up |
Member
My opinion boils down to unless you have a good reason to abbreviate, don't. This is the result of my previous involvement in a project that strictly followed this rule: https://github.com/SerenityOS/serenity/blob/master/Documentation/CodingStyle.md#names
The result is an exceptionally readable codebase at scale. I do believe this is even more relevant for 262 as it uses much more verbose syntax for its pseudo code compared to an actual programming language ( Some examples of what I would consider canonical abbreviations:
I'm sure we could come up with a fairly comprehensive list. From what I can tell the primary motivation for abbreviating in this PR is "there are existing abbreviations". I do not consider that sufficient, and my answer to the problem would be "okay, let's get rid of them". Now, there certainly are cases where abbreviating is fine. I can get behind abbreviating So, in conclusion, as always the answer is "it depends" and IMO we should clarify what exactly we're aiming for before moving forward with a PR like this. If I write a new piece of spec text, how do I tell whether a word should be abbreviated or not? First look at any other occurrence and if there's none I get to pick? Always abbreviate as long as there's a reasonable short variant without creating ambiguity? Never abbreviate except when you find yourself in an AO where the same five syllable word appears 20 times? Are we replacing |
Member
Author
I think I'm on the same page as you, and just drew the line a little closer to the abbreviate side to follow the status quo. I'm perfectly fine with where you seem to want to draw the line. Unfortunately, @syg mostly wanted to increase abbreviation from where it is now. So we'll have to get the group aligned before moving forward. The actual change should be very easy (like 5 minutes) now that all the disparate abbreviations have been normalised.
I was imagining we would have the table of words to abbreviate and which abbreviation to use in the editorial conventions. All other terms should never be abbreviated. Also, as @nicolo-ribaudo brought up at the editor call yesterday, the spell checker should catch deviations for us in CI. |
Collaborator
|
(GitHub won't show the diff, so I can't attach these comments to lines.) |
Member
Author
|
Thanks @jmdyck. Fixed. |
Collaborator
|
In |
Member
Author
|
Thanks @jmdyck! It's unfortunate that ecmarkup couldn't catch that case. |
Member
Author
|
@linusg At editor call today, we decided the best way forward on this PR was for any editors with any objections to an abbreviation listed in the table above to let me know and I will switch all instances of the abbreviation to the full term and add the term to the never-abbreviate list. That also means not acting on @syg's expressed preference for increased abbreviation. Once everyone is happy with the always-abbreviate table, I'll re-run the script to generate the summary of renames, and we can get our final reviews in. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
As mentioned here: #3789 (comment). See my summary below for which words remain abbreviated (and how) and which words are never abbreviated. In a couple places, I decided to reassign an alias that was no longer referenced (usually for coercions) rather than just rename the alias.
Disclaimer: I used AI in the process of creating this PR.
Draft because I want to give it another good review and do some more checks for completeness.