I switch over to my GitHub notifications, take a deep breath, and prepare myself for an hour of context-switching. My feedback’s due on pull requests, and the review process always comes with a lot of variety. Sometimes, the request is in an area in which I’m an expert, and it's easy to provide insightful and actionable feedback. Other times, I find myself reviewing a portion of the codebase that I'm not too familiar with, like a rarely-edited build script or an area of the codebase that I inherited ownership of only recently.
Code review is a significant time commitment, and it is important that we evaluate how engineering teams can make the most of it. The way I see it, the code review process (with the help of some meaningful automation) can be the perfect space for teams to build their async communication skills and contribute to team knowledge sharing.
In this Guide, you will learn:
How code review can help exercise your team’s communication skills
How to use code reviews to bolster knowledge-sharing within your team
How adding automation to the code review process can free up engineers for learning
Trust in async communication
The COVID-19 pandemic ushered in a period of lockdowns that mean many of us are now pretty comfortable working from home (WFH). With this new WFH standard, effective asynchronous communication has become paramount. In addition to email and direct messages, pull request reviews are an option for async communication. Before we talk about why teams should focus on improving their async communication skills, let's quickly rehash the benefits of async communication:
It ensures people across different time zones can feel included in conversations.
It's accommodating for people with different language competencies (human languages, not programming ones).
It provides flexibility to accommodate people with varying schedules.
Developing a robust async communication strategy, especially regarding code reviews, requires two things: trust and standards. Aside from observing your teammate's facial expressions and vocal inflections, you're left to trust their intentions when receiving certain kinds of feedback. Trust should be something that teams work on proactively, and although it is a prerequisite to a healthy code review process, it’s not the only requirement.
Outside trust, standards around how code reviews operate can reduce the friction that comes with ambiguity. For example, clarifying what feedback is a "nit" and what feedback is actually blocking a merge helps clarify expectations for everyone involved in the review process. These problems can be avoided by setting aside time as a team to identify what these standards are.
Then there’s documentation. In my years working on open source projects, I've observed how difficult it is to get great docs up for projects, especially ones that lack a dedicated technical writer. That's why I've become particularly interested in passive styles of documentation: ways that we share information that happen without active participation. Passive documentation includes things like back-and-forth dialogue to investigate a bug over issues, or pull request descriptions. While discoverability might be a challenge for passive docs that don’t have dedicated table of contents or labeling, they provide a low-friction format for knowledge exchange. Not to mention, oftentimes, this kind of knowledge exchange is highly contextualized to the area that is affected.
Now, it's important to call out that developing strong async communication skills and learning to view pull requests as a form of passive documentation go hand-in-hand. As mentioned earlier, passive documentation includes the kinds of artifacts that teams create when they are investigating, designing, and building in public. For teams to be comfortable sharing notes and process on a bug investigation publicly, for example, there has to be a high level of trust within the team and a high level of dedication to the async process.
Let automation streamline processes
I've spent a lot of time talking about the people behind the process of code reviews, but automation can be a helpful tool, too. Sometimes it takes a machine to help people get out of their own way when it comes to collaboration. Over the years, I've seen a variety of automations and software checks in various projects. The introduction of GitHub Actions in 2018, and the marketplace of actions that emerged around it, made it incredibly easy to introduce automated checks into the code review process. But with great power comes great responsibility.
I spent a fair bit of time working with the maintainers on nteract to reason through what checks would make the most sense to enable on the organization's repositories. Ultimately, we settled on a strategy that could be roughly summarized in the following points:
Less is more. A cacophony of checks can make it really difficult for anyone involved in code review to discern what is important and what isn't. Automation, when applied conservatively, can help steer people's attention in the right direction. Too much automation can overwhelm developers and lead to decision fatigue.
Automation as a second brain. Automation should help fill the gaps where human attention can fail. For nteract, this meant adding automation that would capture to-dos introduced in code, and generate issues that could be tracked from them. It also meant including automated code quality checks that reduced some of the review burden that was on the developers, giving them the flexibility to focus on high-concept reviews—as well as the knowledge-sharing mentioned in previous sections.
Automation should empower people. Effective automation should enable people to take strong ownership of certain features. For example, automation that moves feedback from a pull request into an issue and automatically labels and assigns it gives the team higher confidence in who owns which feature areas. Instead of sending this to the abyss of the backlog, automation helps keep the feedback actionable.
Moving forward
Though often thought of as tedious, code review can become fertile ground for planting the seeds of stronger empathy, more active communication, and better knowledge-sharing within teams. And a little automation can go a long way.