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