Dashes
Which dash to use, and how it differs from a colon.
Three marks look alike and do different work. Pick by the job, not by which one the keyboard offers first.
| Mark | Name | Job |
|---|---|---|
- | hyphen | joins words into one modifier |
– | en dash | spans a range |
— | em dash | breaks a sentence open |
Write the character itself rather than an approximation. A pair of hyphens is not an em dash, and a reader copying the text gets the pair.
Recommended: The queue squashes the branch — every message it carried is kept.
Not recommended: The queue squashes the branch -- every message it carried is kept.
Hyphens
A hyphen joins two or more words doing the work of one modifier, and only when they sit in front of what they describe.
Recommended: a command-line tool
Not recommended: a command line tool
After the noun, the words go back to being separate and the hyphen goes away.
Recommended: the tool runs on the command line
Not recommended: the tool runs on the command-line
An adverb ending in -ly is already attached to what follows it, so it takes no hyphen: a newly published package, not a newly-published package.
En dashes
An en dash spans a range, standing in for the word to. It takes no spaces around it.
Recommended: Node.js 20–24
Not recommended: Node.js 20 - 24
If the range is introduced by from or between, finish the phrase with a word rather than a dash: from 20 to 24, never from 20–24.
Em dashes
An em dash breaks a sentence open to let something in — an aside, a correction, a sharp turn — and then lets it close again. Set it with a space on each side.
Use one where a comma is too quiet and parentheses are too polite. Use two to fence off an aside in the middle of a sentence, and make sure the sentence still reads if the fenced part is lifted out.
One pair to a sentence. A second pair leaves the reader unable to tell which aside ended where.
Colons
A colon and an em dash both introduce. They differ in what the reader is promised.
A colon promises that what follows completes what came before — a list, a definition, a quotation. It points ahead, and the text after it delivers exactly what the text before it set up.
An em dash promises nothing in particular. It marks a break in the sentence and lets anything through: an aside, a reversal, a remark the sentence did not need.
Recommended: The check does one thing: it compares the vendored copy against what upstream serves.
Not recommended: The check does one thing — it compares the vendored copy against what upstream serves.
Both are correct English there, and the colon is better, because the sentence before it announced that one thing was coming and the colon is the mark that keeps the promise.
Prefer the colon whenever what follows is the thing that was just announced. Keep the em dash for what the sentence did not announce.
When a colon introduces a list, the phrase before it stands alone as a complete sentence. See Colons for that rule and for the ideographic colon this project uses in commit subjects.