The Problem with Code Review

Every code change at Facebook goes through a Code Review phase; it's integral to the mechanics of shipping code. There are internal tools to support it, it affects how code is written, how tasks are defined, how teams are structured, and how expectations are set. For a lot of engineers it is frequented more often than even the tasks tool.
But just like task systems (e.g. Jira) it is only a system, a tool, a set of features and capabilities; it is... unopinionated. It works just fine even if you fill the summary with cat gifs nd the test plan with "TBA". Each org, team, and individual might see it and use it differently; and most often they do.
And just like task systems, it is often up to the companies, orgs, teams, and individuals to define how they want to use the system. Teams might have a wiki article describing their process, maybe the company does their own intro course, but most often these things aren't formally described, so people tend to learn them via their first few PRs, watercooler chats, a buddy or mentor, or by making mistakes.
When the company is small(-ish) this usually solves itself because there is enough friction between tenured engineers and newcomers to pass the tribal knowledge along, but grow a little too fast and your in a Tower of Babel situation.

Starting the Journey

That is the situation my team was in when I was asked by my manager to go over Code Review best practices for our team. This should have been an easy task, all I needed to do was to collect some points about code review and present it during the last 5 minutes of our next team meeting. I looked around for existing resources and to my surprise they didn't exist, nothing formal, nothing at the company level. This huge part of the company's engineering stack was completely undocumented, no guide or manual, no expectations.
So I had to build it myself. I started collecting notes for myself. The more I thought about it the more I wanted to talk about it: motivations, mechanics, concepts, ideas, aspirations, metrics, techniques, analogies, and examples. But the more I wanted to talk about it the less likely I'll be able to concisely make a point.
I've been burying the lead for too long now, the end result was a set of Code Reviewer Archetypes. I've been a fan of the Gang of Four Design Patterns book since I first encountered it, books like Effective Java, Anti-Patterns, and Martin Fowler's Refactoring all have something in common - once we give something a name we can finally manage it's nuance in our thoughts, and in our conversations with others. When you build a system you consider Factories, Singletons, Observers, and Decorators. Next time you review code you'd be the Doctor, the Teacher, the Mechanic, or the Fortune Teller. These names don't just carry mechanics, they also carry the reasoning behind their existence, elevating discussion from the what to the why, from a Code Reviewing tool, to a Code Reviewing mindset.

Next Up

In the next posts I'll share the concepts I mapped in my presentation, and then post each archetype one-by-one. Feel free to comment, ask questions, and suggest perspectives that I might have skipped or you feel differently about. Also if you have your own stories about the subject I'll love to read them.