Async Teaching Through PR Reviews

Are pull requests the key to teaching less experienced devs at work? Hear one tech lead’s success story.

As a tech lead, part of my everyday job is to carefully review pull requests (PRs) from everyone in my team. Our review process has mutated through the years, and evolved with us as a team—and so in this opinion article I would like to share some of my thoughts on everything regarding PRs and reviews.

First things first, this opinion comes from my work at my current company which (even though we’ve been in the market for over 14 years) still behaves in many ways as a startup. My experience and thoughts here may or may not reflect a your own reality, but hopefully this is enough to spark a conversation or share a new or different point of view.

When I initially started, the team was very small. Small enough that the best way for everyone to be aware and involved in a growing codebase was for everyone to review everyone’s PRs. This was very effective initially because as tech lead it allowed me an opportunity to not only operate as a reviewer, but also as a teacher.

PR reviews should not be exclusively about finding problematic code, but also a great means for more senior developers to take time to explain possible pitfalls and better ways to code or approach a problem to devs with less experience. This, of course, increases the time that is necessary per-PR to get through someone else’s work, but the return on investment is huge.

Starting with a team of folks who were little or not at all familiar with Vue, or even fresh out of coding bootcamps, I now sit comfortably surrounded by a competent team of senior+ developers (and some fresh mids and juniors that are being grown within the team).

Most of my teaching or guiding of these folks has been async through written communication either via Slack or PR review process as I have explained before—mostly due to the fact that for most of my time at this company I have been working on an 8-hour difference in time zones, which made it a very obvious choice.

Would it have been better, however, if we had chosen to operate on a more “standard” way perhaps with a buddy system or direct mentorship? Maybe.

But what I do know for sure is that forcing myself to think carefully about the way that I would explain a concept, as clearly and briefly as possible, greatly enhanced my ability to not only review PRs better, but to be able to squeeze a bit more out of them by making them an educational tool.

Our current process has changed and been refined through the years but still holds the same fundamental value. We no longer operate based on an everyone-reviews-everyone’s-work approach because the amount of time spent reviewing everything would be prohibitive for senior+ developers. So instead we opted for adopting a round-robin style review process where every junior and mid developer is requested to review every PR as part of their day to day, and senior developers are assigned randomly, requiring only one or two senior sign-offs of any PR at any given time.

I cannot stress enough how important it has been for junior and mid devs in particular to participate in the review process of every single PR, while being encouraged to ask questions on parts of the code that they are having trouble understanding. It allows for people to, as slowly as needed, take in the information and process it, or even support it with research of their own.

The more common approach by buddy systems or pairing mode is, of course, also very valuable, but for some folks can be daunting and hard to follow. The teacher or higher level dev is often too wrapped up in trying to solve the problem at hand, or build the feature, to best take the time to explain in-depth concepts.

Note that I’m not saying that pairing is not an incredibly valuable tool to get people acquainted with the codebase, or even to help them grow as developers. It is, and it should continue to be a practice that we all do—but I’m suggesting that it has a few pitfalls and it may not be the best fit for all teachers and students.