Skip to content

Building Software Together

A practical guide to code review.

Writing code with other people is hard. Thankfully, companies like GitHub have built great tools to help make it easier. Tools so great that it’s difficult for me to remember the days before GitHub Pull Requests with easy-to-follow conversations through inline comments on diff files.

Even with great tooling like this, however, it can still be challenging avoid miscommunication that can sometimes create resentment between team members. Here are a few tactics I’ve learned over the years to foster community.

  1. Author your comments from the perspective of the team when possible by using plural pronouns (e.g. we, our, us) to convey that all code contributed is a team effort.
  2. Provide an explanation for the “why” behind your requested changes (e.g. outline the pros and cons of both the current and proposed approach to a problem) to avoid the perception of arbitrary demands.
  3. When providing a personal opinion or preference, leave opportunity for feedback on the topic (e.g. “What are your thoughts on what I have proposed?”) to promote collaboration.

Communicating tone and intent via text is difficult. Using collaborative language can go a long way towards unifying a team around the common goal — shipping great software.