Politeness in code review keeps attention on the code rather than the person. Replace accusatory “you” with collaborative “we,” and ask for changes instead of issuing commands. section 6.2 section 6.4
Use these wording choices when requesting a change:
- Basic: “You should move the Vehicle class to a separate file.” section 6.2
- Improved: “We should move the Vehicle class to a separate file.” section 6.2
- More collaborative: “Can we move the Vehicle class to a separate file?” section 6.2
Make a request specific
Combine the request with its rationale and expected result: “Needs change: Can we move the Vehicle class to a separate file? This follows our team guidelines (link) and will improve the readability of this section.” section 6.2 section 6.4
Before sending, check whether the comment sounds polite, friendly, and outcome-focused. Remove combative or passive-aggressive wording, take a break if needed, and use technical language and broadly understandable analogies. section 6.2
Figure 6.6 Toxic comment unigram breakdown. “You” is statistically more likely to be found in comments labeled toxic.
Compare the prominence of “you” in toxic comments with code-focused wording. section 6.2
Figure 6.7 Nontoxic comment unigram breakdown. Technical terms, like “tests,” “files,” or “pull request” are statistically more likely to be found in comments labeled nontoxic.
Contrast personal wording with technical terms associated with nontoxic comments. section 6.2
