Code reviews are a common practice at many software companies. Being a good recipient of a code review is just as important as producing quality reviews for others. The key to handling both of these situations well is to approach them as learning opportunities. A good code review should maintain code health, encourage healthy team communication, and result in members of the team learning something new.
Code reviews can be stressful for both parties. The person being reviewed is putting their code out there for everyone to see and potentially judge, while the person reviewing feels pressure to maintain quality without being nitpicky or coming across as harsh.
Here are five strategies that to improve your code review process.
1. Remember that Everyone is (Potentially) Watching
Code reviews are typically public, and people other than you and the person reviewing your code may stumble upon the pull request. All of the usual rules of civility apply, and in an industry with an overabundance of imposter syndrome, it helps to approach code reviews with empathy. Remember, the person reviewing your code has less context than you do. If they ask a question for which the answer seems obvious, don’t be dismissive or respond in a way that may embarrass them.
If you think they’re lacking the proper amount of context to review the code effectively, schedule a meeting and walk them through the code in-person.
2. Talk Through Your Approach
Before you’ve even written a single line of code, talk through your approach. This attention to detail will ensure that the process is productive and effective. It might seem obvious, but it’s surprising how often a solution is created without thinking about whether or not it fits in with a larger architectural pattern or guideline that governs the codebase.
If you aren’t sure how to tackle a chunk of code from a high level, ask for ideas and feedback, rather than staying quiet. Getting the approach right from the beginning saves rework and ensures that the reviewer can focus on smaller code health issues. If the entire project has to be reworked, the reviewer won’t have the capacity to focus on smaller issues that may be present in the next iteration.
3. Write a Thorough Summary
There are many elements that factor into a good pull request summary:
- Description: Always accurately describe what you did and the decisions you made
- Areas of Trouble: Preemptively draw attention to any areas of the code where you feel unsure
- Hacks: If you used a hack somewhere in the project, call it out yourself and ask for suggestions for improvement
A clear and well-written summary opens dialogue early and can build trust within your team. When you bring up an issue in your summary, your reviewer will:
- Have an idea of where to put their focus, as they may not have time to review the entirety of your code
- Know you weren’t trying to sneak something past them
- Have the context necessary to review the code
4. Meet in Person
If you’re producing large pull requests that introduce pieces of architecture, it might be worth scheduling an in-person walkthrough of the code and functionality first. Discussing the code will give the reviewer important context that will be useful during later evaluation.
While meeting in-person many take time, you’ll save time in the long run by explaining any confusing pieces of code the reviewer would have had to figure out themselves. By giving them the big picture up front, you reduce the risk of confusion during the review process.
5. Take It Offline
If you take issue with a suggestion that someone makes during a code review, ask the reviewer to take the discussion offline. Discussing your thoughts in-person, without the threat of potential onlookers, can lead to a more productive conversation and potentially, a compromise.
In an ideal world, we would all experience positive code reviews. If you find yourself struggling to engage in a productive review, try out a few of the strategies covered here. Share any tips or tricks that you’ve used for effective code reviews below!