Skip to content
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.

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

Refactor docs to cover both names and identifiers #655

Merged
merged 1 commit into from
Mar 7, 2024
Merged

Conversation

foolip
Copy link
Collaborator

@foolip foolip commented Feb 29, 2024

Add more examples and document the additional shortening from names to
identifiers that we've done in many cases.

Add more examples and document the additional shortening from names to
identifiers that we've done in many cases.
@foolip
Copy link
Collaborator Author

foolip commented Feb 29, 2024

While writing this I encountered a few issues:

  • structuredClone() has "structured-clone" as the identifier and checkVisibility() as "check-visibility", but scrollIntoView() has "scrollintoview". Should we change it to "scroll-into-view" or add "match caniuse when shorter" to the guideline?
  • should "array-copywithin", "array-findlast", "array-fromasync", and "array-isarray" be separated into words even though that makes the identifiers longer than the names? What about "bigint"?
  • The identifiers "viewport-relative-units" and "viewport-relative-unit-variants" are not derived from the names at all
  • What about features names for case-insensitive attribute names or values like "modulepreload" and "tabindex"? Do we need to explain why we use those names?

Dear reviewers, please don't block this PR on figuring out the answers to all of these issues, but keep them in mind :)

@ddbeck
Copy link
Collaborator

ddbeck commented Mar 6, 2024

  • structuredClone() has "structured-clone" as the identifier and checkVisibility() as "check-visibility", but scrollIntoView() has "scrollintoview". Should we change it to "scroll-into-view" or add "match caniuse when shorter" to the guideline?

I think structured-clone is special being a global and that "structured cloning" is something said by documentation and such. But perhaps check-visibility should be renamed to something like element-checkvisibility and elements-scrollintoview, keeping in the spirit of the Array method identifiers. (see also #656 (comment)).

  • should "array-copywithin", "array-findlast", "array-fromasync", and "array-isarray" be separated into words even though that makes the identifiers longer than the names? What about "bigint"?

Continuing from my previous point, perhaps we need a guideline for single interface method features. Those feel like "easy" cases where we might just use the method name and move on.

In the case of bigint, I think developers just say "bigint" and "bigints" and less commonly "big ints", so we have that to go on here.

  • The identifiers "viewport-relative-units" and "viewport-relative-unit-variants" are not derived from the names at all

I think I'm responsible for these and I tried to rely phrases "known to be in widespread use by web developers." I tried to validate this by reading blog posts and Stack Overflow questions about their use. I don't think it'd be outrageous to use the unit names directly, but the description field fills that need too.

  • What about features names for case-insensitive attribute names or values like "modulepreload" and "tabindex"? Do we need to explain why we use those names?

It wouldn't hurt to make that explicit for names, though I think the "lowercase alphanumeric" bit handles the identifiers already.

(Also, I learned today that the values are case insensitive! I had long assumed that the sequence of bytes given by modulepreload was significant, not the sequence of letters. Fascinating!)

@ddbeck
Copy link
Collaborator

ddbeck commented Mar 7, 2024

But perhaps check-visibility should be renamed to something like…

Over in #655 (comment), Philip makes a good case for preferring brevity over consistency across the whole set of features. (That said, we should prefer consistency when we add text to distinguish things for ambiguity, as in the case of arrays and typed arrays.)

@foolip
Copy link
Collaborator Author

foolip commented Mar 7, 2024

Thanks for the review @ddbeck! I'll merge this and we should keep going in #548 with the guidelines.

@foolip foolip merged commit f332031 into main Mar 7, 2024
2 checks passed
@foolip foolip deleted the docs-names branch March 7, 2024 16:05
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.

2 participants