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.