1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
# Punctuation detail
Detail for all punctuation marks. Source: developers.google.com/style
(Colons, Commas, Dashes, Ellipses, Hyphens, Parentheses, Periods, Quotation
marks, Semicolons, Slashes).
## Colons
- A colon introduces closely related information (lists, examples, etc.).
- The text before a colon must stand alone as a complete sentence:
- Recommended: "The fields are defined as follows:"
- Not recommended: "The fields are:"
- The first word after a colon is lowercase, except proper nouns, headings,
quotes, or after labels like "Caution:"/"Warning:".
- Prefer a colon over an em dash to introduce a list.
## Commas
- **Serial comma** — always, in a series of three or more:
- "zones, regions, and multi-regions" (never "...zones, regions and
multi-regions").
- After introductory words and phrases: "Finally, only groups that contain
parameters appear in this list."
- Between independent clauses joined by *and/but/or*.
- Before *which* in nonrestrictive clauses; after conjunctive adverbs
(*however, therefore*).
- Generally no comma before *because* unless it introduces a nonrestrictive
clause.
## Dashes (em dash)
- Em dash (—) marks a break or interruption. No spaces around it: "To
indicate a break in the flow of a sentence—or an interruption—use an em
dash."
- HTML: `—`; macOS: Option+Shift+hyphen.
- Don't use en dashes; use hyphens or the word "to" for ranges ("2015 to 2020",
not "2015–2020").
- Prefer a colon or period over a dash to separate items from their
descriptions.
## Ellipses
- In general don't use ellipses (…). They're for omission in quoted material
mid-sentence only — not at the start or end of a quote, and never for
hesitation ("The answer is ... wait for it ...").
- When describing UI elements, omit ellipses from labels unless they're part of
the label's meaning.
- When used, format as three periods with spaces: "word ... word".
## Hyphens
- Use to avoid misreading, combine terms, and separate word parts.
- Compound modifiers before a noun: "a two-day total", "a high-level overview".
- Don't hyphenate compound modifiers after the noun ("the total was two days").
- Prefixes: hyphenate `self-`, `cross-`, before capitalized nouns or numbers
("pre-2015", "non-English").
- Compound nouns generally closed ("username"), but check the word list and
established conventions.
- No spaces around hyphens (except suspended hyphens: "two- and three-day").
- When in doubt, consult the word list and existing docs in your project
before guessing.
## Parentheses
- Don't put important information in parentheses — some readers skip them.
- Keep parentheticals short; otherwise use two sentences.
- Prefer em dash or commas where a parenthetical is borderline:
- Recommended: "Enter a name for the instance—for example, my-instance-99."
- Recommended: "Enter a six-digit hex number (for example, 228B22), and then
click OK."
- Not recommended: "Enter a name for the instance (for example,
my-instance-99)."
- If a full standalone sentence is inside parentheses, the period goes inside.
- Don't use parentheses for optional plurals ("file(s)").
## Periods
- End complete sentences with a period (exceptions: headings and some list
items).
- Periods with URLs: avoid URLs at sentence end so the period isn't mistaken
for part of the URL; rewrite or put the URL on its own line.
- Quotations: period goes inside the quotation marks even if not part of the
quote.
- Parentheses: full sentence inside → period inside; partial → period outside.
- No periods in acronyms/initialisms or headings; use them in abbreviations
like "e.g." and "etc.".
- No double spaces after a period.
## Quotation marks
- Use straight double quotes and apostrophes only — never curly/smart.
- Used mostly for titles of shorter works (articles, episodes) when not linked;
for literal UI strings that aren't code; sparingly otherwise.
- Commas and periods go inside the closing quote; other punctuation outside
unless part of the quote.
- Single quotes only for quotes within quotes and code examples.
- Don't put quotation marks around link text.
## Semicolons
- Avoid when possible. A semicolon is OK to:
- Join two closely related independent clauses where a period feels too
strong and a comma too weak: "compute the centroid; if it is on the
opposite side, reverse the order."
- Precede a conjunctive adverb (*therefore, however*) joining clauses:
"...below the Main Camera; therefore, only the stereo cameras are
affected."
- Separate a series of long or complex items that contain their own
punctuation.
- Otherwise use a period or comma.
## Slashes
- Avoid outside code. Use *and* or *or* instead of `/`:
- "the requirement isn't supported" for "and/or" ambiguity — use the word
that matches the meaning.
- Never in dates ("2017-04-15", not "4/15/2017").
- No abbreviations like `c/o` or `w/`.
- OK in file paths and URLs (backslash on Windows).
- Break long URLs after a forward slash.
|
