Guidelines for short names

[foolip]

Short names were added in #545 and @ddbeck suggested guidelines at #545 (comment).

[foolip]

It's worth thinking more about sentence case vs. Capitalizing Every Word. #545 was merged with sentence case. I've sent #549 to show what would change if we capitalize.

These cases are not great with sentence case:

• Cascade layers and Container queries, which I've seen capitalized many, many times.
• Constraint validation API, where the trailing "API" makes it look more like a typo.
• Web animations, which seems more generic and might cover CSS animations as well.

And these cases are not great when capitalized:

• "Flexbox Gap", but we could make it "Flexbox gap"
• "input Event", although that would be less strange as "input Event"
• More generally, any name that ends with "attribute", "event", "method", "property" or similar, which we'll have more of in a future long name. Consider "CSS aspect-ratio Property", where aspect-ratio feels squashed in between those Big Words.

@tidoust also pointed out that https://github.com/w3c/browser-specs has a shortTitle property, and that capitalizes every word.

I'm still leaning towards keeping sentence case, but am not at all committed to it.

[tidoust]

Regarding shortTitle property values in browser-specs, the W3C Manual of Style recommends to "Capitalize title words following U.S. usage". Most if not all specification titles follow that convention.

The same manual also lists some commonly misspelled terms with the example of "real-time communications", where capitalization depends on whether the term is used in titles and headings (and references to titles and headings) or to talk about the generic idea.

Applied to web-features, the rule of thumb could perhaps depend on whether the feature has a strong bond with a specification or a heading in a specification (e.g., "Container Queries" could perhaps be seen as strongly tied to the "Container Queries" section of the CSS Containment spec), or whether we're more talking about a generic idea, or a generic idea applied to something specific (e.g., "CSS aspect-ratio property" because property is a generic idea. Plus the spec actually uses lowercase in the heading for that ;))

[captainbrosset]

I made some comments about the guidelines listed in #545 which, I'm realizing now, would make more sense in this issue here:

• CSS: Let syntax and casing—such as : (for pseudos), @ (for at-rules), and kebab-case—do the talking (e.g., ":indeterminate" not ":indeterminate pseudo-class").

I'm on the fence about this one because I always think about beginners. It feels much more beginner-friendly, from my opinion, to say things like "has pseudo-element" rather than ":has", or "dialog html element" rather than "<dialog>".

Note that it could be a mix of both: ":has pseudo" and "<dialog> element". But, asking people to recognize a tiny syntax character to know what we're talking about feels like an unnecessary barrier to me.

• HTML: Tags can stand in for the concept of an element (e.g., "<img>" not "<img> element" or "Image element").

What if we have an SVG element feature at some point. How would someone know if "<foo>" is SVG or HTML?

[foolip]

@captainbrosset do you think a longName or structuredName would address the first concern? I'm imagining names like "CSS aspect-ratio property", "CSS :has() functional pseudo-class", or "HTML <dialog> element" for those.

For the <tagname> convention, I'd say that <tagname> means HTML, and we should prefix with SVG to disambiguate, like here:

web-features/feature-group-definitions/svg2-script-html-equivalence.yml

Line 1 in 3ea8af9

name: "SVG <script> async & defer"

[foolip]

#565 is a case where I felt like "CSS translate, scale, and rotate properties" was the short possible name. Guidelines should at least allow for that, or ideally guide us in the same direction in the same situations going forward.

[captainbrosset]

Sure, a long name would address my concern. But now I'm wondering if we need ID, shortName, and longName. Maybe just ID and longName?

[foolip]

We might be able to get away with a single kind of name, I'm not sure. Right now there are no consumers for the names we've added, and probably a good next step is to talk to some people we think will show them...

caniuse.com is the main consumer I have in mind, so looping in @Fyrd here.

[ddbeck]

Mentioning #291 so we can have a guideline for HTML attribute features, someday.

And editing to add: #321

[foolip]

Copying what I wrote in #624 (comment):

We have no guidelines for when the name should look like code or not, but some precedent. So far we have these names with () in them:

• :has()
• :indeterminate()
• :is()
• :where()
• Array at()
• Array flat() and flatMap()
• checkVisibility()
• color-mix()
• CSS abs() and sign()
• CSS calc()
• CSS calc() constants e, pi, infinity, and NaN
• CSS min(), max(), and clamp()
• CSS pow(), sqrt(), hypot(), log(), exp()
• CSS round(), mod(), and rem()
• CSS sin(), cos(), tan(), asin(), acos(), atan(), and atan2()
• image-set()
• input.showPicker()
• scrollIntoView()
• select.showPicker()
• structuredClone()

Roughly, my thinking has been that when adding () or other small pieces of syntax hints towards what kind of thing it is, then do it even though it's not minimal. My thought has been that we'll eventually mark up names with <code> and have names like this:

• :has()
• Array flat() and flatMap()
• CSS abs() and sign()
• input.showPicker()
• structuredClone()

I think this has very little downside in the cases of global/static things like :has() or structuredClone().

For instance methods (stuff on prototypes) it's a little bit inconsistent, already. I think we should favor short names, and for Array the style works.

For HTML elements it's a bit awkward and I'm not sure the choices so far will stand, but the alternatives to input.showPicker() that I've considered are worse IMHO:

• HTMLInputElement.prototype.showPicker() (much worse)
• HTMLInputElement showPicker()
• <input> showPicker()

[foolip]

@ddbeck had some very useful thoughts and feedback in #655 (comment). Noting that here since I'll merge the PR, to not lose the discussion.

[foolip]

What to do about the Web prefix has come up in #691, so I'll write down my thoughts here. Our guideline is "Avoid frequently-used abbreviations and nouns, such as API and Web", but I had to use the example "web workers" as one of the few "obvious" cases, and I don't think we can always omit Web.

Based on MDN and what's in WPT, here's a fairly comprehensive list of what the specs call themselves:

• Web Animations
• Web Audio API
• Web Authentication
• Web Bluetooth
• Web Cryptography API
• Web Locks API
• Web MIDI API
• Web Neural Network API
• Web NFC
• Web Serial API
• Web Share API
• Web Share Target API
• Web Speech API
• WebCodecs
• WebGL (multiple specs)
• WebGPU
• WebHID API
• WebOTP API
• Web Packaging
• WebRTC (multiple specs)
• WebSockets
• WebTransport
• WebUSB API
• WebVTT
• WebXR Device API (multiple specs)

A few more phrases that aren't the names of specs:

• Web Components: refers to Shadow DOM, Custom Elements, etc.
• Web Messaging: refers to postMessage() etc.
• Web Notifications: refers to Notifications API
• Web Storage: refers to localStorage and sessionStorage
• Web Workers: refers (arguably) to the kinds of workers defined by HTML, but not service workers