How to level up the code-review culture on your team
Find that code reviews are taking days to get to completion? Code reviews are an essential part of shipping high-quality code. But sometimes it can feel like your team is at a standstill when they’re not prioritized effectively.
Code reviews can be a source of frustration. It’s natural to want to focus on your own task and to see code reviews as stealing your focus from deep work.
As a result, you could have a tendency to try and rush through a list of pull requests. Or put them off until they threaten to get in the way of moving a feature forward. But with both approaches you’re missing an opportunity to strengthen the culture of your team.
For Derek Prior, a staff engineering manager at GitHub, code reviews are how you build the right culture at your company.
“Code review is the discipline of discussing your code with your peers that drives a higher standard of coding,” said Prior at RailsConf.
Those discussions around code give you insight into your team, encourage knowledge sharing, and drive innovation. You’re not stuck in code reviews. They’re the path to getting unstuck.
Code reviews can be a grind. They can bring out our worst habits. But, they can also help you understand the needs of your team and forge deeper connections.
By building a good code review culture, you will make a better culture for your team. Here’s how to do it.
1. Find your code review bottleneck.
Before you can change the code review process, you have to understand where it is breaking down. There’s always a bottleneck with code reviews. And if you’re a founder or senior engineer, it may very well be you.
Developers with the most experience are the ones on your team most likely to be asked to check out code. It’s a lot of work. And a lot of weight. A backlog of reviews might even be blocking progress in other areas like shipping a new feature.
Maybe you’ve already recognized the problem. So, you started to train someone. But training takes time and trust. Meanwhile, your backlog of pull requests is growing.
Change begins with acknowledging that someone on your team is carrying too much of the burden. Remember, a senior engineer is often not the only one who can review a piece of code.
Your team wants more ownership. And you’re probably ready to clear your plate. So, how do you lighten your load and give them the opportunity?
2. Assess your team’s attitude and comfort with code reviews.
When you notice that all of your code reviews are being done by the same person or a short list of people, Uma Chingunde, VP of Engineering at Render, recommends asking this question:
“Is everyone feeling confident to do code reviews?”
Even the most functional teams struggle with how to comment in code reviews. In the early stages of remaking your code review process, encourage teammates to remember there’s a human behind the code.
Gergely Orosz, the developer behind the blog and newsletter The Pragmatic Engineer, believes empathy plays a big role in better code review culture.
Start by acknowledging that members of your team might still be learning your guidelines or parts of the code. Then, he recommends focusing on “explaining alternative approaches,” and submitting reviews that are “very positive in tone, celebrating the first few changes to the codebase that the author is suggesting.”
There are lots of reasons why members on your team aren’t taking on code reviews. You won’t know why unless you ask. Here’s how Uma suggests digging into what’s happening.
“If someone on the team doesn’t review, then have a chat,” said Uma. “You can say, ‘I notice you don’t review.’ It’s possible they don’t feel confident or they don’t get the value.”
Your teammate’s answer will let you know if you need to look at how you’re communicating, sharing knowledge, or assigning code reviews. Spoiler alert: It’s all of the above.
3. Good communication begins with clear, concise pull requests.
Ambiguity is a quick way to side track code reviews. The best outcomes — whether it’s code reviews or brainstorming — come from asking distinct, meaningful questions.
The team at Palantir, in a blog post about code review best practices, has developed a practical method for streamlining the code review process.
“”Only submit complete, self-reviewed (by diff), and self-tested CRs,” notes the Palantir team. “In order to save reviewers’ time, test the submitted changes (i.e., run the test suite) and make sure they pass all builds as well as all tests and code quality checks, both locally and on the CI servers, before assigning reviewers.”
Take the time to catch the things that are obvious. You’ll make it easier for the reviewer to get at what’s important and you’ll benefit from insight into challenges you can’t solve on your own.
For Prior, the pull request is the opening of a conversation. The request author provides context — he suggests two paragraphs (focusing on what you’ve learned) for each change — to help the reviewer understand why a given code choice was made. That explanation is also relevant to future discussions because it becomes part of the commit.
The reviewer of the code, in turn, should “ask questions rather than making demands.” By framing potential changes as questions, you’ll encourage discussion that makes space for multiple perspectives and the chance to share knowledge about why a given idea could be the best way forward.
4. Track how long it takes for code reviews to be completed.
As you begin to incorporate more of your team into the code review process, things could naturally slow down.
So, what should you do if code reviews are taking too long? Uma thinks this is a great time for another check in with your engineers.
“If people take too long to do reviews, is it because they’re too busy doing their own thing? Or is it because they find it hard to review the code?”
It’s typically some combination of other responsibilities and unclear expectations that may lead to a slower pace of code reviews. In order to overcome that inertia, you will have to intentionally build time into your team’s schedule and reassess how you assign code reviews.
5. Optimize your schedule by using pause points for code reviews.
Code reviews don’t have to be a drag on productivity. By building in time around natural pause points, you can avoid disrupting your flow and the cost of context switching. Take the 30 minutes before lunch or after the morning stand-up to review code.
Regular time set aside for reviews minimizes begins to build a habit. You might even use whatever comes next — an espresso or walk around the block — as a reward for completing a code review while you’re establishing that habit.
This strategy is a way to effectively use the time when you’re transitioning away from meetings or coming out of deep work. If it’s following a stand up meeting, the code review could even begin with a short dialogue with the author of a pull request to help give you additional context or emphasis beyond what’s been typed.
6. Assign code reviews to establish expectations for your team.
Your team might be operating under the assumption that code reviews aren’t their responsibility. Asking for someone to contribute isn’t enough to break that assumption. You have to assign code reviews to each member of your team to make it clear this is a shared responsibility.
There are a number of ways to structure assignments. Here are two ideas that could work for your team: Pair engineers together on tasks so you don’t need separate reviews or assign reviews via a rotation system.
Pairs are a useful construct because they facilitate dialogue. And you don’t need to explicitly assign someone to a review. You write each piece of logic as a pair — one person “driving” (typing) — as the other person reads and discusses their code. There will inevitably be more ideas shared and different approaches.
You’re introducing a partner to speed up the pace of play. While pairing, you automatically have a built-in code review as you write the code together. That knowledge — that someone will back you up — also alleviates the stress of feeling like you have to handle everything.
We’re currently evaluating automatic code review assignments. Creating an automatic assignment rotation helps both the author of a pull request and the assignee. Make sure there’s a clear way for team members to tell everyone, whether in Slack or somewhere else, that they’ve claimed a code review.
An automated system reduces decision fatigue for your engineers. It eliminates the feeling that code review may be a burden and the cost of trying to remember who you last tapped for a review assignment. Perhaps, most importantly, it supports a culture of code reviewing by making it clear that everyone will take a turn.
You can always add in an option to override the automatic assignment if you need someone on your team with specific skills to review your code.
Building a sustainable code review culture encourages productive debates and unexpected insights. Team ownership of code strengthens relationships by defusing conflicts and preventing burnout.
Your team might get by without a well-defined code review process. But establishing clear practices and expectations around code review can help your team better share the load and move forward more smoothly and efficiently.
Photo by renee_ek on Unsplash.
Cara Borenstein is Co-Founder and CEO at Stashpad - note-taking that feels like messaging. She previously worked in engineering at Twilio and is an alum at Columbia University.
