Group pull request reviews can be a great way to share knowledge and generate discussion. This practice can help developers gain the confidence to start reviewing areas of the code new to them.
How does a group pull request review work?
The PR author should lead the group review. While group reviews should be informal, take a few minutes to prepare so you can present your work cohesively.
Introducing Your PR
It’s important to make sure the team has some context before diving into the changes. This can look different depending on your teammates’ level of experience with the area of code you worked on. Here are some different ways I’ve introduced my changes in a group review:
- Saying, “This is the new endpoint to fetch users who have signed up for marketing emails.”
- Sending out a link to the user story before the review so that others can read the requirements in detail.
- Pulling up system architecture diagrams to show how data will flow between microservices.
Once your team has a high-level understanding of what you worked on, you have a few options. You can do a quick demo, which is a great option for UI work. For less user-facing work, you might want to show the documentation changes, such as an updated OpenAPI doc, or a new README.
Getting Into the Details
At this point, you’ll want to pull up your code. That might be in the diff view on the pull request page or in your local IDE. The diff view works well for more straightforward changes. If you suspect you’ll need to jump around in the code to explain how everything works together, using your IDE can make that simpler.
Every code base and feature is different, so there’s no one way to walk through your changes. A good rule of thumb is to start at the highest level of abstraction, and then move down into the implementation details. That usually means starting with something like an API controller method or the entry point to a script.
Unit tests usually aren’t very useful to review as a group, but they can be good for highlighting edge cases or other special scenarios. On the other hand, integration tests are an ideal way to show how your work fits into the rest of the system.
Asking for Feedback on the Spot
If there are areas where you’re looking for input, point them out as you go. Here are some examples of areas that you might ask for specific feedback on:
- A function that is mysteriously slow
- A bloated class that needs some refactoring
- The exact wording of an error message
Encourage your teammates to chime in with their thoughts. Don’t forget to note any changes they suggest so you can address them later.
How do group reviews help the team?
Group reviews require a time investment from the team, so they should provide value to everyone who attends.
The PR author saves time.
Reviewing PRs is usually done asynchronously. It may take a lot of back-and-forth comments over hours, or even days, to decide how to fix an issue the reviewer pointed out. By meeting up synchronously as a team, you should get a lot of feedback in real-time. You can also ask clarifying questions about the feedback on the spot. Sometimes it even makes sense to edit the code during the review, like when you’re rewording an error message.
Reviewers know where to begin.
Group reviews should be more efficient for the reviewers as well. While a group review isn’t intended to go over every line of code, it should give the reviewers a headstart on their detailed review. If the PR author asks for specific input, the reviewer also knows where to spend extra time providing feedback.
It can also make reviewing subsequent PRs for the same feature go faster. Walking through the changes should help the reviewer get more familiar with that area of the codebase and understand why a feature is being built in a particular way.
Other developers learn.
In an ideal world, all the developers at the review will have some feedback for you. In reality, probably one or two of your teammates will have a lot of input and the rest will mostly listen. This isn’t a bad thing. Just being present (and paying attention!) will still help developers get comfortable working in a new area of the code base.
You can hear what the experts in that area of the code comment on and see the coding conventions and design patterns used. Even if you’re just listening to a more senior developer discuss something with the PR author, you’re gaining a deeper understanding of what factors to consider when working in that area of the code.
How do I get my team to do a group pull request review?
Just ask! Group reviews work best when initiated by the PR author. When you’re deciding if you should ask your team for a group review, make sure it’s a good fit. Some examples of good situations for a group review:
- You’re the only developer on your team who has worked on a particular microservice so far. You’ve added a simple new endpoint to query some data. Now, you want to walk through the different areas of the microservice where you needed to make changes so your teammates can easily pick up the next backlog item for adding a similar endpoint.
- You’re introducing a new framework for running integration tests, and you want to make sure your teammates understand how to add new test cases.
- You had to improvise on the design for a UI feature, and you want some feedback on how to improve it.
This type of review should be pretty informal and also shouldn’t take more than 15 or 20 minutes. I’ve found that the best time for group reviews is right after standup when everyone is already gathered in a room or on a Zoom call. Try to avoid creating separate calendar invites. Keeping it casual is best for getting discussion flowing and making it approachable to more junior developers who might be intimated by presenting during a scheduled meeting.