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.

Sign up for GitHub

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

Jump to bottom

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

Closed
martinthomson opened this issue Jul 30, 2024 · 4 comments · Fixed by #550
Closed

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

martinthomson opened this issue Jul 30, 2024 · 4 comments · Fixed by #550
Assignees
@martinthomson
Labels
Status: In Progress We're working on it but ideas not fully formed yet. Topic: Meta

Comments

@martinthomson
Copy link
Contributor

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
Copy link
Contributor

hober commented Jul 30, 2024

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
Copy link
Member

Big +1 to either formulation.

@domenic
Copy link
Member

domenic commented Sep 10, 2024

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
Copy link
Contributor Author

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.

@LeaVerou LeaVerou added Status: In Progress We're working on it but ideas not fully formed yet. Topic: Meta labels Dec 3, 2024
@martinthomson martinthomson self-assigned this Jan 30, 2025
martinthomson added a commit to martinthomson/design-principles that referenced this issue Jan 30, 2025
@martinthomson
Use names that describe purpose
7611b68 
I found that I needed to redo the whole section here.
Changing the focus seemed better than adding text.
This is more text, but not a lot more.

Future-proofing is one motivation, but it's not the real motivation for
these recommendations.

I also found the key event example to be spectacularly non-compelling.
It even made me think that it is almost a bad example.
Key events can be synthesized by speech recognition tools in some cases.

To that end, I chose an example that I'm more familiar with.

Closes w3ctag#507.
@martinthomson martinthomson mentioned this issue Jan 30, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@martinthomson martinthomson

Labels
Status: In Progress We're working on it but ideas not fully formed yet. Topic: Meta
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Use names that describe purpose martinthomson/design-principles
4 participants
@hober @martinthomson @LeaVerou @domenic