A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).

Specs/style: Difference between revisions

From WHATWG Wiki
Jump to navigation Jump to search
(→‎Spelling: Use "cannot".)
(→‎Terminology: Equality)
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
When writing a spec, it is suggested that you adhere to the following guidelines.
To be effective, specs must be written clearly and consistently, using precise and succinct language.
 
To facilitate those goals, it is suggested that spec editors adhere to the style guidelines set forth in this document.


== Spelling ==
== Spelling ==


; Unless otherwise stated, use standard American English spelling.
; Use standard American English spelling, unless otherwise stated below.
: Continue the history of the Web and use 'en-US' spelling for your specs and the technologies they document. See [[wikipedia:Wikipedia:Manual of Style/Spelling|Wikipedia's Manual of Style for spelling]] for assistance.
: Continue the history of the Web and use 'en-US' spelling for your specs and the technologies they document. Consult [[wikipedia:Wikipedia:Manual of Style/Spelling|Wikipedia's Manual of Style for spelling]] for assistance.
; Use "acknowledgements" instead of "acknowledgments".
; Use "acknowledgements" instead of "acknowledgments".
: Whenever 'dg' represents the "soft" /d͡ʒ/ sound, it should be followed by an 'e' or an 'i', to ensure it is not confused with the "hard" /dɡ/ sounds.
: Whenever 'dg' represents the "soft" /d͡ʒ/ sound, it should be followed by an 'e' or an 'i', to ensure it is not confused with the "hard" /dɡ/ sounds.
; Use "dialogue" for the noun and "dialog" for all other parts of speech.
: Whenever a word has a '-log(ue)' dichotomy, only keep '-ue' for the definitive noun: "monologue", "dialog box", "catalogging", "homologous".
; Use "cannot" when something is impossible or prohibited.
; Use "cannot" when something is impossible or prohibited.
: "Can not" implies a choice; "cannot" prevents one.
: "Can not" implies a choice; "cannot" prevents one.
== Punctuation ==
; Use the Oxford comma.
: When conjoining three or more items, place a comma between the second-to-last item and the conjunction.
; Use double quotation marks for outer quotes and single quotation marks for inner quotes.
: This is slowly becoming the worldwide standard anyway, but just in case you need to be reminded.
; Where applicable, use double quotation marks for quoted terms or scare quotes and single quotation marks for literal sequences of characters.
: You ''could'' use double quotation marks for the latter, but single ones are less bulky. Besides, it's better to use semantic markup and/or styling to get the message across anyway.
; Only include between quotation marks what is actually being quoted.
: It's OK to have punctuation on the outside of a quotation mark. It's even OK to have punctuation on both sides of a quotation mark, if that's how things turn out.
; Avoid parenthesizing an entire sentence within another sentence.
: It's OK to let a parenthetical sentence stand on its own.
; Include trailing punctuation within parentheses.
: You should be able to remove a parenthetical without breaking anything around it; if you have trailing punctuation outside parentheses, removing the parenthetical will leave the punctuation orphaned.


== Terminology ==
== Terminology ==
Line 16: Line 31:
=== Bags of bits ===
=== Bags of bits ===


; Be careful of your use of the terms "file" and "resource".
; Be careful with your use of the terms "file" and "resource".
: Make sure your definitions refer only to bags of bits, and not also stuff in the Real World™ (like baskets of apples).
: Make sure your definitions refer only to bags of bits, and not also to stuff in the Real World™ (like baskets of apples).
 
=== Collections of values ===
 
{| class="wikitable" style="min-width: 50em;"
|+ For a keyless collection of values, use the provided term when … and …
|-
!
! uniqueness doesn't matter
! uniqueness matters
|-
! order doesn't matter
| style="text-align: center;" | "unordered list"
| style="text-align: center;" | "set"
|-
! order matters
| style="text-align: center;" | "list"
| style="text-align: center;" | "ordered set"
|}
 
{| class="wikitable" style="min-width: 50em;"
|+ For a keyed collection of values, use the provided term when there can be … and …
|-
!
! only one key per value
! more than one key per value
|-
! only one value per key
| style="text-align: center;" | "bidirectional map"
| style="text-align: center;" | "map"
|-
! more than one value per key
| style="text-align: center;" | "inverse map"
| style="text-align: center;" | "multimap"
|}
 
; Use "object" for a map whose values can be functions.
: This helps to distinguish cases where values might not be static data types.
; Do not use "dictionary" for any collection of values.
: There is potential for confusion between a map (which, as mentioned above, can have only one value per key) and a Real World™ dictionary (which can have more than one definition per headword).


=== Willful violations of other specs ===
=== Willful violations of other specs ===
Line 23: Line 77:
; When willfully and deliberately violating standards set out in other documents, use the term "willful violation" instead of simply "violation".
; When willfully and deliberately violating standards set out in other documents, use the term "willful violation" instead of simply "violation".
: "Violation" makes you sound naughty; "willful violation" makes you sound knowledgeable.
: "Violation" makes you sound naughty; "willful violation" makes you sound knowledgeable.
; When willfully and deliberately violating standards set out in other documents, carefully document the differences from the standards in question, as well as the rationale for each decision to differ.
: If you don't explain your decision making, there will be no incentive to follow your standard over the existing one.
=== Equality ===
; Use the form "<var>X</var> is <var>Y</var>" when defining a term.
: A definition asserts that the relationship between <var>X</var> and <var>Y</var> exists and is one of absolute equality.
: "A '''baz''' is a foo that bars."
: <code><var>X</var> === <var>Y</var></code>
; Use the form "<var>X</var> is <var>Y</var>" or "<var>X</var> is equal to <var>Y</var>" when comparing for equality.
: A conditional questions whether the relationship between <var>X</var> and <var>Y</var> is one of equality.
: "If ''baz'' is equal to ''foo'', then bar."
: <code><var>X</var> == <var>Y</var></code>
; Use the form "set <var>X</var> to <var>Y</var>" when assigning a value.
: Make all assignments explicit and unambiguous.
: "Set <var>foo</var> to 'bar'."
: <code><var>X</var> = <var>Y</var></code>


[[Category:Spec coordination|*]]
[[Category:Spec coordination|*]]

Latest revision as of 01:36, 25 February 2015

To be effective, specs must be written clearly and consistently, using precise and succinct language.

To facilitate those goals, it is suggested that spec editors adhere to the style guidelines set forth in this document.

Spelling

Use standard American English spelling, unless otherwise stated below.
Continue the history of the Web and use 'en-US' spelling for your specs and the technologies they document. Consult Wikipedia's Manual of Style for spelling for assistance.
Use "acknowledgements" instead of "acknowledgments".
Whenever 'dg' represents the "soft" /d͡ʒ/ sound, it should be followed by an 'e' or an 'i', to ensure it is not confused with the "hard" /dɡ/ sounds.
Use "cannot" when something is impossible or prohibited.
"Can not" implies a choice; "cannot" prevents one.

Punctuation

Use the Oxford comma.
When conjoining three or more items, place a comma between the second-to-last item and the conjunction.
Use double quotation marks for outer quotes and single quotation marks for inner quotes.
This is slowly becoming the worldwide standard anyway, but just in case you need to be reminded.
Where applicable, use double quotation marks for quoted terms or scare quotes and single quotation marks for literal sequences of characters.
You could use double quotation marks for the latter, but single ones are less bulky. Besides, it's better to use semantic markup and/or styling to get the message across anyway.
Only include between quotation marks what is actually being quoted.
It's OK to have punctuation on the outside of a quotation mark. It's even OK to have punctuation on both sides of a quotation mark, if that's how things turn out.
Avoid parenthesizing an entire sentence within another sentence.
It's OK to let a parenthetical sentence stand on its own.
Include trailing punctuation within parentheses.
You should be able to remove a parenthetical without breaking anything around it; if you have trailing punctuation outside parentheses, removing the parenthetical will leave the punctuation orphaned.

Terminology

Bags of bits

Be careful with your use of the terms "file" and "resource".
Make sure your definitions refer only to bags of bits, and not also to stuff in the Real World™ (like baskets of apples).

Collections of values

For a keyless collection of values, use the provided term when … and …
uniqueness doesn't matter uniqueness matters
order doesn't matter "unordered list" "set"
order matters "list" "ordered set"
For a keyed collection of values, use the provided term when there can be … and …
only one key per value more than one key per value
only one value per key "bidirectional map" "map"
more than one value per key "inverse map" "multimap"
Use "object" for a map whose values can be functions.
This helps to distinguish cases where values might not be static data types.
Do not use "dictionary" for any collection of values.
There is potential for confusion between a map (which, as mentioned above, can have only one value per key) and a Real World™ dictionary (which can have more than one definition per headword).

Willful violations of other specs

When willfully and deliberately violating standards set out in other documents, use the term "willful violation" instead of simply "violation".
"Violation" makes you sound naughty; "willful violation" makes you sound knowledgeable.
When willfully and deliberately violating standards set out in other documents, carefully document the differences from the standards in question, as well as the rationale for each decision to differ.
If you don't explain your decision making, there will be no incentive to follow your standard over the existing one.

Equality

Use the form "X is Y" when defining a term.
A definition asserts that the relationship between X and Y exists and is one of absolute equality.
"A baz is a foo that bars."
X === Y
Use the form "X is Y" or "X is equal to Y" when comparing for equality.
A conditional questions whether the relationship between X and Y is one of equality.
"If baz is equal to foo, then bar."
X == Y
Use the form "set X to Y" when assigning a value.
Make all assignments explicit and unambiguous.
"Set foo to 'bar'."
X = Y