This page contains rules about using hyphens and dashes, including em dashes and en dashes, in developer documentation. Because of the visual similarities between these punctuation symbols, these rules are especially restrictive in favor of comprehension and legibility.
Use only the keyboard hyphen (-). Don’t use em dashes or en dashes because they are easy to mistake for a hyphen and for each other, especially for readers with low vision. To set off an interruption or an added comment in the middle of a sentence, use commas or parentheses. To introduce an expansion or a list, use a colon. In description lists, separate the term from its description with a colon or period, not a dash. When text already uses em dashes, rewrite each sentence with commas, parentheses, a colon, or a period. Review the sentence structure instead of replacing each em dash mechanically.
Examples
- ✓ The request fails (usually with a 429) when you exceed the rate limit.
- ✗ The request fails—usually with a 429—when you exceed the rate limit.
- ✗ The request fails — usually with a 429 — when you exceed the rate limit.
- ✓ The client caches the token locally, so repeated calls skip the network round trip.
- ✗ The client caches the token — a locally stored copy — so repeated calls skip the network round trip.
Rationale
Em and en dashes differ from each other and from the hyphen mainly by length, which makes them difficult to distinguish, especially for readers with low vision. Frequent em dashes are also a common sign of AI-generated text. Commas, parentheses, colons, and periods can do the same work. An em dash often joins clauses loosely, so replacing only the mark can leave the relationship between the clauses unclear.
Don’t use en dashes. Use a hyphen or the word to for number ranges.
Examples
- ✓ Ports 3000 to 3005 are reserved.
- ✗ Ports 3000–3005 are reserved.
Rationale
An en dash differs from a hyphen and a minus sign mainly by length. A keyboard hyphen or the word to makes the endpoints of a range easier to identify.
Don’t place spaces on either side of a hyphen, except in suspended hyphens where a space may follow (but not precede) the hyphen.
Examples
- ✓ Use a read-only token.
- ✗ Use a read - only token.
- ✓ This applies to two- and three-node clusters.
Rationale
A hyphen normally binds the words on either side. Spaces make the hyphen look like a dash or a separate mark. In a suspended form such as two- and three-node clusters, a space follows the first hyphen because the shared word is omitted.
When two or more words together modify a noun, hyphenate them, as in a 30-second timeout and a high-priority task. Don’t hyphenate when the unit is an abbreviation or symbol, as in a 16 GB drive, or when the compound follows the noun in predicative position.
Examples
- ✓ Cancel the high-priority task first.
- ✗ Cancel the high priority task first.
Rationale
A hyphen groups words before a noun so the reader can identify the complete modifier. In a 30-second timeout, the hyphen shows that 30 and second together modify timeout. A unit abbreviation such as GB already identifies the unit, so the hyphen has nothing to group. After the noun, the compound no longer needs a hyphen to show which word it modifies.
Hyphenate a compound modifier when its unit is spelled out, as in a 5-foot cable, but not when the unit is an abbreviation or symbol, as in a 5 ft cable.
Examples
- ✓ Connect a 5-foot cable.
- ✗ Connect a 5 foot cable.
- ✓ Connect a 5 ft cable.
- ✗ Connect a 5-ft cable.
Rationale
In a 5-foot cable, the hyphen joins the number and the spelled-out unit into one modifier. In a 5 ft cable, the abbreviation ft already identifies the unit and needs no hyphen.
Hyphenate location compounds such as lower-left corner and top-right portion.
Examples
- ✓ Select the icon in the lower-left corner.
- ✗ Select the icon in the lower left corner.
Rationale
In lower-left corner, the hyphen joins lower and left into one direction. Without the hyphen, the two words can appear to be separate modifiers.
Write a prefixed word as one word when that spelling is established, as in email, runtime, subdomain, and nonprofit. Use a hyphen when the prefix is cross-, self-, all-, or ex-; when the base word is a proper noun; when the closed form is ambiguous, hard to read, or a different word; or when the compound isn’t well established yet. When in doubt, check the word list.
Examples
- ✓ Add a subdomain for each environment.
- ✗ Add a sub-domain for each environment.
- ✓ Create a cross-region replica.
- ✗ Create a crossregion replica.
Rationale
Writing an established prefixed word as one word matches its familiar spelling. A hyphen shows the prefix boundary when closing the word makes it ambiguous, difficult to recognize, or a different word.
Prefer to write compound nouns as one word unless convention or the word list establishes a hyphenated or open form.
Examples
- ✓ Check the changelog before upgrading.
- ✗ Check the change-log before upgrading.
Rationale
Writing an established compound as one word matches its conventional spelling. The word list records the guide’s choice when more than one form is in use.
Hyphenate terms with a z- prefix, such as z-index, z-order, and z-axis, rather than closing them up.
Examples
- ✓ Set the
z-index so the modal stacks above the toolbar.
- ✗ Set the
zindex so the modal stacks above the toolbar.
Rationale
When the z- prefix is closed up, the letter can look like part of the base word. The hyphen shows the prefix boundary and matches the conventional spelling.
Don’t hyphenate compound modifiers that include an adverb ending in -ly.
Examples
- ✓ a fully managed service
- ✗ a fully-managed service
Rationale
The -ly ending identifies fully as an adverb modifying managed. Readers can see that the two words work together in a fully managed service without a hyphen.
In general, don’t hyphenate a compound modifier that follows a linking verb.
Examples
- ✓ The API is well documented.
- ✗ The API is well-documented.
Rationale
A compound after a linking verb is in predicate adjective position. In The API is well documented, well documented follows the linking verb is and describes the API instead of modifying a following noun. Without a following noun, a hyphen doesn’t need to group the two words.