search

w3ctag / design-principles

A small-but-growing set of design principles collected by the TAG while reviewing specifications
https://w3ctag.github.io/design-principles
178 stars 46 forks source link

New principle: name things for what they do, not how they do it #507

Open martinthomson opened 3 months ago

martinthomson commented 3 months ago

This was brought up in our discussion of the Web Translation API.

In that example, the means by which translation is accomplished, AI (or ML), was used as part of the name.

hober commented 3 months ago

In the translation case, the fact that the API can be backed by LLMs is an implementation detail. "Do not expose implementation details in naming."

LeaVerou commented 3 months ago

Big +1 to either formulation.

domenic commented 2 months ago

I wonder how this design principle would look on existing APIs like navigator.gpu: should it be navigator.graphicsDisplay?

Or even things like "CSS": should it be "style and layout control" instead of talking about the specific mechanisms behind such control?

martinthomson commented 2 months ago

navigator.gpu seems to be concretely about graphics processors, though navigator.graphics would be equally fine (graphicsDisplay, in addition to being more verbose, might refer to a monitor).

We already have div.style for a CSS API and <style>, so arguably the principle is already being followed there. Obviously we have a ton of CSSBlah types defined, so it's not perfect, but it's not that bad.