-
Notifications
You must be signed in to change notification settings - Fork 72
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
Conversation
docs/guidelines.md
Outdated
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. |
There was a problem hiding this comment.
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. 😅
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this 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.
docs/guidelines.md
Outdated
@@ -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. |
There was a problem hiding this comment.
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.
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. |
There was a problem hiding this comment.
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.
docs/guidelines.md
Outdated
|
||
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". |
There was a problem hiding this comment.
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:
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". |
Based on conversation in #1764 (comment)