Guideline for feature IDs for interfaces and methods

[foolip]

We currently have a mix of two styles for features named after interfaces or methods.

All as one word:

• CloseWatcher → "closewatcher"
• getHTML() → "gethtml"
• requestIdleCallback() → "requestidlecallback"

Hyphenated:

• EditContext → "edit-context"
• getComputedStyle() → "get-computed-style"
• requestVideoFrameCallback() → "request-video-frame-callback"

I think we should bless one style.

[foolip]

BigInt64Array is an awkward case if we wanted to always hyphenate. big-int64-array???

If removing hyphens, OES_texture_half_float_linear and other WebGL extensions are a challenge. oestexturehalffloatlinear is a bit too novel IMHO, not an improvement.

[jcscottiii]

Here's an example that did not hyphenate. (So it further illustrates the need for some guidelines)

Float16Array

• File: float16array

[ddbeck]

This came up in the WebDX call yesterday. I don't feel strongly about this, but I thought it would help to think through how we'd describe the rule. After writing it out, I decided that I like the appearance of the hyphens style better and though that it might be more convenient for certain kinds of transformations (e.g., you can convert the hyphens style to camelCase). But found the pattern more difficult to explain.

For the WebGL extensions, we could probably have a special rule in either case that says to convert underscores to hyphens (_ to -).

So one of these, perhaps?

All one word style

If a feature is named for an API, CSS property, or other literal identifier that you would find in a web developer's source code, then propose an ID that takes the identifier, removes any non-hyphen non-alphanumeric characters (i.e., [^a-zA-Z0-9\-]), and sets the remaining characters to lowercase.

If a feature has a descriptive name, then propose an ID that replaces any spaces with hyphens, removes any non-alphanumeric characters, and sets the remaining characters to lowercase.

• ✅ Name: inert → ID: inert
• ✅ CloseWatcher → closewatcher
• ✅ getHTML() → gethtml
• ✅ View transitions → view-transitions
• ❌ requestIdleCallback() → request-idle-callback

Hyphens style

If a feature is named for an API, CSS property, or other literal identifier that you would find in a web developer's source code, then propose an ID that takes the identifier, inserts hyphens between each word in the identifier, removes any non-hyphen non-alphanumeric characters, and sets the remaining characters to lowercase.

If a feature has a descriptive name, then propose an ID that replaces any spaces with hyphens, removes any non-alphanumeric characters, and sets the remaining characters to lowercase.

• ✅ Name: inert → ID: inert
• ✅ CloseWatcher → close-watcher
• ✅ getHTML() → get-html
• ✅ View transitions → view-transitions
• ❌ requestIdleCallback() → requestidlecallback

[foolip]

Thanks @ddbeck!

One small benefit of the one word style I can see is that you could often tell from the identifier if something is named after code as opposed to CSS. But I don't love that identifiers will seem less consistent at first glance.

In the hyphens style, how do you think we should treat BigInt64Array and Float16Array in this style? How about features named after all-lowercase HTML attributes but which are clearly separate words, like writingsuggestions?

Do you have a strong preference?

[foolip]

As a minor point in favor of the hyphens style, @mfreed7 was quite reasonable assumed in https://chromium-review.googlesource.com/c/chromium/src/+/6495042 that kRequestclose was a mistake. If we use hyphens between words, then camelCased forms of the IDs would be more readable.

[ddbeck]

In the hyphens style, how do you think we should treat BigInt64Array and Float16Array in this style?

In the hyphens style, I believe the rule would call for naming the features big-int-64-array and float-16-array. Weird, but we're going to end up with weird things from time to time.

How about features named after all-lowercase HTML attributes but which are clearly separate words, like writingsuggestions?

Ugh, I guess we can either amend the guideline to say something like, "don't willfully ignore obvious word breaks that should exist" (getting writing-suggestions) or say "be aggressively unthinking about it" (getting writingsuggestions). I'm inclined toward the latter, just because it makes it easier to review—there can be no debate about whether to break words (e.g., we never have to decide things like e-mail or email).

[ddbeck]

(This has me wishing we had made the IDs more arbitrary. If I were starting this today, I'd probably have advocated for something goofy like writingsuggestions-5be5af, where the real identifier is a random hex suffix, which is immutable once the feature is minted, and the human readable-ish prefix would've only been exposed as an array for lookups.)