Specs/style: Difference between revisions

Revision as of 20:21, 6 November 2013

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

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.

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.

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).

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	"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.

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.

@@ Line 14: / Line 14: @@
 == Punctuation ==
+; 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 have a parenthetical sentence stand on its own.
+: 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.