Ambiguous pronoun references
Avoid vague and confusing references between a pronoun and its antecedent.
Not recommended: If you type text in the field, it doesn't change.
Recommended: If you type text in the field, the text doesn't change.
Not recommended: The name of the function to execute in the given script. It does not include parentheses or parameters.
Recommended: The name of the function to execute in the given script. The name does not include parentheses or parameters.
In many cases, it's best to use these types of words as adjectives modifying nouns instead of using them as pronouns.
Not recommended: Set this to true.
Recommended: Set this value to true.
Don't use gender-specific pronouns unless the person you're referring to is actually that gender.
In particular, don't use "he," "him," "his," "she," or "her" as gender-neutral pronouns, and don't use "he/she" or "(s)he" or other such punctuational approaches. Instead, use the singular "they."
But if you really can't stand using singular "they," then rewrite to avoid singular gendered pronouns. Using plurals can often help. For more suggestions, see The Chicago Manual of Style, 16th edition, section 5.225, "Nine techniques for achieving gender neutrality."
Use optional pronouns, such as "that" and "who," to avoid ambiguity and clarify meaning in sentences.
Not recommended: Make sure all the files are correct.
Recommended: Make sure that all the files are correct.
Not recommended: Right-click the link you want to open.
Recommended: Right-click the link that you want to open.
Avoid first-person pronouns ("I," "we," "us," "our," and "ours") except in the following contexts:
- The questions in FAQs.
- A document whose author makes comments in the first person.
- Using "we" to refer to your organization, after using your organization's name. For example, "Example Pet Store recommends that you feed your aardvark Standardized Aardvark Treats. We cannot guarantee the happiness of your aardvark otherwise."
Use the second-person pronoun ("you") whenever possible.
For more information about second person, see Second Person.
There are several relative pronouns. This section concerns only three of them: "that," "which," and "who."
"That" and "which" don't mean exactly the same thing, so don't substitute one for the other:
- "That" introduces a restrictive clause. It isn't preceded by a comma.
Recommended: The echidna that has a long snout is furry.
This sentence describes a particular echidna, the one that has a long snout.
- "Which" introduces a nonrestrictive clause and is preceded by a comma.
Recommended: The echidna, which has a long snout, is furry.
This sentence describes all echidnas, and mentions in passing that they all have long snouts.
For more information about restrictive and nonrestrictive clauses and whether to use "that or "which," read what Grammar Girl has to say on the subject.
When referring to a person, use "who," not "that."
Not recommended: Grant access to the authenticated user that provides an invitation token.
Recommended: Grant access to the authenticated user who provides an invitation token.
However, you can use "whose" to refer to people, animals, and things. "Whose" is the possessive form of both "who" and "which."
Recommended: Examine the variables whose values are set at compile time.