Plain English: A Cheat Sheet of Things to Be Wary Of
Oversights and style issues that can lead to ambiguity
1 It’s, its
“It’s a good idea to break the module into its functional parts.”
2 They’re, their, there
“They’re unsure of their direction. It’s neither here nor there.”
3 That, of
Ask myself if it's needed.
“We picked the framework that we liked most.”
“Once inside of the host, we made our first lateral move through the network.”
4 Who, whom, that
Use who if the person is the subject, whom if the person is the object, and that if it’s an object or if it’s a group of objects or people.
“David Tennant, whom I like, and who played Doctor Who at one point, is a charming man.”*
5 Which, that
Which when the quality is merely descriptive. That when the quality identifies the thing in a set of similar things. A clause starting with which has a comma on either side and removing the clause doesn’t change the sentence’s meaning. Aesthetically, that is less intrusive.
“The Monaco Editor is the code editor which that powers VS Code.”
“The Monaco Editor, which is loved by thousands of developers, is the code editor that powers VS Code.”
6 Many, much
Many if I can count the thing, much if I can’t.
“This function is complex—it has too many lines.”
“This function is complex—there’s too much going on in it.”
7 Fewer, less
Fewer if I can count the thing, less if I can’t.
“Fewer meetings means less anxiety at the end of the day.”
8 Imply, infer
Imply means something being true is tied to something else being true.
“The study’s results are shown to two decimal places, which implies the analysis must be precise.”
“The codebase is modular, which implies it is easy to maintain.”
Infer means an understanding of something gives me reason to make a guess about something else. With an implication, it’s someone else doing it. With an inference, I’m the one making it.
“I can infer from our retention numbers that the product isn’t really sticking.”
9 Farther, further, faather
Farther for real concepts. Further for abstract ones. Faather if John F. Kennedy had been cast as Darth Vader.
“I’m further along with this writeup than I had thought.”
“I’m farther down the street.”
“No, I am your faather … Luke.”
10 Collective nouns
Refer to a set of people using a singular verb, unless you want to emphasize the set’s members.
“The team is happy with the schedule.”
“The company is doing well.”
“Management are deliberating about how to respond to the recent attack on our backbone.”
11 Mostly consensus, most, plurality, sizable
There’s either a consensus or there isn’t one.
Most suggests more than half.
Plurality means a substantial group, though not necessarily most.
Sizable means a decently-sized group.
Use the term that most accurately reflects reality.
12 Utilize, employ, enumerate
Use is better than utilize.
Use is better than employ.
List is better than enumerate.
13 Uninterested, disinterested
Uninterested means not interested. Disinterested means impartial and is generally a good thing.
“The disinterested investor was uninterested in my ‘gut feelings’ about interest rates.”
14 Literally, actual
Do I mean to say literally—as in, in a literal sense—or do I mean to say figuratively?
Do I mean to say actual—as in, not abstract—or do I mean to say current?
“They’ll literally lose their minds when they hear the production servers went down on release day.”
“The experiment’s actual current setup is straightforward.”
15 Affect, effect
Affect is a verb. Effect is a noun.
“To affect an idempotent function’s effects, you have to pass it different arguments.”
16 Lay, lie
You lie down. You lay something down. Their present and past tenses are a bit strange.
“Lie down, so I can lay a copy of Les Misérables on your face. Have you lain here before? Have you laid anything on your face before? I lay here once and laid a book on my face. It was glorious.”
17 Towards, whilst, amongst
Toward is more colloquial than towards. Either way, pick one and stick with it.
18 So, as we all know, rather, it turns out, right
Avoid preambles that presuppose facts about the world without evidence.
“The goal of life is to be happy, right.”
“It turns out, the goal of life is to be happy.”
“As we all know, the goal of life is to be happy.”
19 Time of day
Suffixes denoting the time of day are a.m. and p.m. or AM and PM. Always with a single space before it.
8 AM, 8 a.m., 8 A.M., 8 am, 8AM
20 '90s
Apostrophes replace the omitted part of a word.
“Why are you adding double colons between links? Are you from the 90's '90s?”
21 Nineteenth century
The eighteenth century means the 1700s, the nineteenth century means the 1800s, and so on.
“In several ways, nineteenth-century Cornwall was like today’s Silicon Valley.”
22 Em dashes (—) and hyphens (-)
“Checking in a file is straightforward—select the file, wait for it to finish uploading, then press the check-in button.”
No dash for the verb (checking in), an em dash to say what follows explains what was just said, and a hyphen for the compound noun (check-in). Don’t capitalize the first letter after the em dash.
Not all compound nouns have hyphens. Hyphenated ones that have been in use for a while may lose their hyphens. For instance, email and today. Compound adjectives that precede nouns always have hyphens.
“There’s no need to check in the checked-in file.”
23 Suspended hyphens
When the phrases two-week Sprints and three-week Sprints are squished together, they become two- to three-week Sprints.
“The Scrum team will have two- to three-week Sprints, depending on how many demos we have to give.”
24 Mixing ‘, ', and `
The left single quotation mark (‘), apostrophe ('), and grave accent (`) are different characters. However I choose to use them, be consistent. Slack, Google Docs, and some native editors will automatically change an apostrophe to a left or right quote depending on context.
25 Possession
A sentence with an apostrophe often reads better than one that doesn’t have one.
“The metadata of the file.”
Rewrite as
“The file’s metadata.”
No apostrophes for plurals, even if the word is an abbreviation, acronym, or foreign.
“Each team’s quarterly report ought to have three How-Tos and two demos.”
26 Apostrophes for words ending in S
Scanners’s is usually clearer than Scanners’, especially if the font or formatting make the trailing apostrophe hard to see.
27 Superfluous words, imperatives, and annotations
“This application supports Node v1.1 and v1.2.”
Rewrite as
“This application supports Node 1.1 and 1.2.”
“To read more, click here.”
Rewrite as
“Read more”
“In the past, we’ve, We’ve always done design reviews early on in the process.”
“The meeting is at 4 p.m. in the afternoon.”
28 Stylizing proper nouns
GitHub, not Github.
JavaScript, not Javascript
Photoshop, not PhotoShop.
Salesforce, not SalesForce.
Facebook, not FaceBook.
Reddit is OK as Reddit, since it’s stylized as “reddit” only in its logo.
29 Numbers
Unless they’re meant to be compared to one another, part of an equation, or referencing a table or figure, spell out numbers under 10 and those that are at the start of a sentence. Write all other numbers using numerals.
30 Units
Append units to numbers every time. Precede units with a single space. Capitalize them according to the SI guidelines, or according to the USCS guidelines if using Freedom units.
“The page’s time to first paint is 80 ms and its time to first meaningful paint is 600 ms.”
31 Parentheses
Parentheses break a line’s flow. Can I rewrite the sentence so I don’t have to use them?
“We’ve put together a simple (proof-of-concept right now) app for rendering arbitrary animations.”
Rewrite as
“We’ve put together a proof-of-concept for rendering arbitrary animations.”
32 Them, he or she, him or her
Pronouns are less personal and can lead to ambiguity. Avoid them as a replacement for him or her and they as a replacement for he or she. It breaks a sentence’s subject-verb agreement. Avoid him or her if possible.
“The user journey begins with a user clicking the Start button. He or she The user may then choose between a Simple and a Custom flow. If they the user choose chooses Simple, the whole process ought to take no more than twenty seconds.”
33 Colons
A colon says that what follows is a list of things. Don’t capitalize the first letter after the colon.
“During the postmortem session, we’ll cover three things: things that went well, things we can learn from, and things we think we could have done differently.”
“During the postmortem session, we’ll cover things that went well, things we can learn from, and things we think we could have done differently.”
34 Forward slashes
Separate items in a list with commas, not forward slashes. With commas, the conjunction or disjunction is explicit—and, or—whereas with a forward slash it’s often an implicit disjunction, or occasionally, an implicit ‘these two things are interchangeable.’
“Buttons/menus/data graphics Buttons, menus, and data graphics constitute UI components.”
35 Comma at the end of a series
A comma before the final conjunction or disjunction in a series, while not required, can reduce ambiguity.
“Good code is consistent, understandable, and maintainable.”
36 Active voice
The active voice is more personal than the passive voice.
“The command should be run.”
Rewrite as
“Run the command.”
37 Bullet points
Full sentences, ideally. A period at the end of each line, unless the line is a fragment.
38 Could care less
The correct phrase is Couldn’t care less.
“I couldn’t care less what the critics think. I know the team did a phenomenal job.”
39 Define acronyms
Define an acronym the first time I use it, unless it’s undeniably ubiquitous among all my readers.
“Multi-factor authentication (MFA) continues to trend up across the industry. Table 1 shows MFA numbers from the past year.”
40 Capitalize acronyms
JSON, not json.
OK, not ok.
41 Title capitalization
Capitalize the first word in an email subject or section heading and don’t worry about the rest. That’s easier to remember than which style manual allows me to capitalize which words.
42 Abbreviations
Avoid if possible. Spell things out.
43 Starting emails
Add a comma after the greeting. As far as I can tell, only publishing people care about this one.
“Hi, Fred.”
“Fred, hi.”
44 Ending emails
I’d avoid Best—the email equivalent of a Facebook happy birthday.
45 Etc
Often not needed and only serves to make an idea imprecise. If the series really is infinite, maybe replace it with and so on.
“Analyzing complexity means looking at lines-of-code, files, code paths, etc.”
Better to say
“Analyzing complexity means looking at lines-of-code, files, code paths, and dependencies.”
46 Et al
Outside of academia, using et al is a bit strange. Maybe replace it with and colleagues, and company, or and team.
47 E.g. and i.e.
They’re awkward and not universally understood in the same way. Maybe replace them with English words.
For instance, instead of e.g.
Put differently, instead of i.e.
48 Ellipses
Ellipses replace the missing part of a line or series with three dots, each optionally separated from the other with a space, and the first dot preceded by a space. Don’t append it to etc. Don’t capitalize the first letter after the ellipses. To avoid ellipses possibly breaking when a line wraps, use the ellipses character instead of typing three dots.
The focus group’s top comment was, “The modal doesn’t work well on mobile … and is finicky on desktop.”
“1, 9, 15, 21, …, 29”
49 Citations
Square brackets reference other content or external material. They’re not read as part of the sentence. They exist, but aren’t acknowledged.
“Code quality is closely associated with coupling and cohesion [1].”
And not
“[1] shows that code quality is closely associated with coupling and cohesion.”
50 Double negatives
I love double negatives. Even so, I try to avoid them. In writing as well as in coding.
“If we don’t address the ambiguity, we’ll find ourselves, not impossibly, heading down a difficult path.”
“This prototype is not dissimilar similar to the old prototype.”
51 Jack and I
Generally, use I if I’m the subject and me if I’m the object.
“Jack and I ate a pie.”
“The talking pie ate Jack and me.”
If I take out Jack and does the sentence still sound right?
52 Worst, worse
Worst is what someone who likes using superlatives might say. Worse means something is not better than something else.
“We have the worst roads, folks. The worst roads.”
“This morning’s poker game was the worst. It was worse than the time I lost our Q1 budget to Jenny in Software Engineering.”
53 Due to
The sentence has to make sense when I replace due to with some form of caused by.
“My insomnia is due to all the traveling I’ve been doing.”
“I worked from home due to because of traffic.”
54 Very, just
Ask myself if adverbs like very and just add any value to a sentence.
“Now that we’re caching queries, the app is very fast.”
“I'm very happy thrilled with how the product video turned out.”
“I'm very sad devastated we couldn't get more headcount for the upcoming fiscal year.”
“I'm just reaching out to confirm our meeting this afternoon.”
55 Split infinitives
An infinitive is the word to followed by a verb. It’s an atomic action, thought, or emotion. Splitting an infinitive is adding an adverb in between those two things.
“To boldly go where no man has gone before.”
Rewrite as
“To go, boldly, where no man has gone before.”
56 Ironically
Avoid using ironically to mean coincidentally.
“Ironically, Coincidentally, I like watching the pre-election debates too.”
“Ironically, The BBC won’t air Would I Lie to You in December because of the pre-election debates.”†
57 Principal, principle
Principal is the most important thing in a set of things. Principle is a fundamental truth.
“Our principal design guideline is ‘Don't try to be clever.’”
“Our human interface guidelines are informed by the principles of usability and consistency.”