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

Shorthand and longhand styleguide entry #1891

Merged
merged 5 commits into from
Oct 15, 2024

Conversation

jamesnw
Copy link
Collaborator

@jamesnw jamesnw commented Oct 2, 2024

Based on conversation in #1764 (comment)

@jamesnw jamesnw requested a review from ddbeck October 2, 2024 15:55
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Oct 2, 2024
Comment on lines 200 to 202
In CSS, use the terms "shorthand" and "longhand" to describe the relationship
between CSS properties that combine multiple properties into a single
declaration and the individual properties.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Contrasting with what not to do would be cool, here I think.

Also, I'd been using sembr in this file, or at least one-sentence per line. I don't feel strongly on that point though.

One thing is left unanswered: should I use "longhand properties" or "longhands". I think I prefer the former, but I'd like to know whether I am alone in this. 😅

Suggested change
In CSS, use the terms "shorthand" and "longhand" to describe the relationship
between CSS properties that combine multiple properties into a single
declaration and the individual properties.
Prefer the terms "shorthand" and "longhand" to describe the relationship between CSS properties that combine multiple properties into a single declaration and the individual properties.
Avoid the phrase "constituent properties" for longhand properties, even though this is common on MDN Web Docs.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing is left unanswered: should I use "longhand properties" or "longhands". I think I prefer the former, but I'd like to know whether I am alone in this. 😅

I added a bit of clarification here-

Avoid using these terms without the word "property", so prefer "The text-wrap CSS property is a shorthand" over "The text-wrap CSS shorthand", and "It is a longhand property of..." over "It is a longhand of".

I think what matters is that shorthand and longhand don't replace the word "property" but rather clarify the type of property, but we don't need to say "*hand property" in that order, necessarily.

Copy link
Collaborator

@ddbeck ddbeck left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really like this version! I'm going to request reviews from the active folks around here, so it gets some extra visibility ahead of merging.

@@ -195,6 +195,15 @@ Omit "is used" where there's no loss in meaning.
For example, prefer "The feature reads…" over "The feature is used to read…"
([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635981))

#### longhands and shorthands

Prefer the terms "shorthand" and "longhand" to describe the relationship between CSS properties that combine multiple properties into a single declaration and the individual properties.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prefer assumes that these terms are better than another alternative. But this sentence doens't mention an alternative. So let's use "use" instead. We can also use "properties" here directly, since we are later saying that we shouldn't forget it.

Suggested change
Prefer the terms "shorthand" and "longhand" to describe the relationship between CSS properties that combine multiple properties into a single declaration and the individual properties.
Use the phrases "shorthand property" and "longhand property" to describe the relationship between CSS properties that combine multiple properties into a single declaration and the individual properties.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree on "use". I'd prefer not to refer to it as a phrase with "property", because "The property is a shorthand" is valid, for instance.


Prefer the terms "shorthand" and "longhand" to describe the relationship between CSS properties that combine multiple properties into a single declaration and the individual properties.

Avoid using these terms without the word "property", so prefer "The `text-wrap` CSS property is a shorthand" over "The `text-wrap` CSS shorthand", and "It is a longhand property of..." over "It is a longhand of".
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some formatting helps parse this sentence:

Suggested change
Avoid using these terms without the word "property", so prefer "The `text-wrap` CSS property is a shorthand" over "The `text-wrap` CSS shorthand", and "It is a longhand property of..." over "It is a longhand of".
Avoid using "shorthand" and "longhand" without the word "property":
* Prefer "The `text-wrap` CSS property is a shorthand" over "The `text-wrap` CSS shorthand".
* Prefer "It is a longhand property of" over "It is a longhand of".

@ddbeck ddbeck merged commit 5e1629a into web-platform-dx:main Oct 15, 2024
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants