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
m (→‎Spelling: see -> consult)
(→‎Terminology: Add guidelines for terms for collections of values.)
Line 18: Line 18:
; Be careful of your use of the terms "file" and "resource".
; Be careful of 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 stuff in the Real World™ (like baskets of apples).
=== Collections of values ===
{| class="wikitable" style="min-width: 40em;"
|+ For a keyless collection of values, use the following 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: 40em;"
|+ For a keyed collection of values, use the following 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;" | "strict dictionary"
| style="text-align: center;" | "dictionary"
|}
; Use "object" for a map whose values can be functions.
: This helps to distinguish cases where values might not be static data types.


=== Willful violations of other specs ===
=== Willful violations of other specs ===

Revision as of 18:25, 6 November 2013

When writing a spec, it is suggested that you adhere to the following guidelines.

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 "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.
"Can not" implies a choice; "cannot" prevents one.

Terminology

Bags of bits

Be careful of 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).

Collections of values

For a keyless collection of values, use the following 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 following 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 "strict dictionary" "dictionary"
Use "object" for a map whose values can be functions.
This helps to distinguish cases where values might not be static data types.

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.