A Guide to Mindful Communication in Code Reviews

Summary

Code reviews are presented as both technical work and communication, teaching, and learning. The guide defines mindful communication as listening and speaking with compassion, kindness, and self-awareness, then applies that perspective to reviewers and authors. It recommends self-checking before commenting, asking open questions instead of assuming, omitting linter-detectable nits, signaling what can wait, giving example code and documentation, and ending substantial feedback with “What do you think?” Reviewers are encouraged to approve unless major problems exist, while large changes and architectural decisions should receive broader discussion. Authors should link relevant documentation, assume good intent unless feedback is hostile, keep diffs focused, and seek feedback early; these practices take time but can become a learnable habit that varies by team.

Takeaways

1. 1

   Reviewers are encouraged to ask why an author chose an approach and use open questions rather than declaring the code wrong.

2. 2

   Comments that a linter could catch should generally be omitted, and nonessential improvements can be deferred to a later or follow-up change.

3. 3

   Large changes and architectural decisions warrant broader conversations than a code review, while focused diffs and early feedback can reduce review stress.