How many of you are doing code reviews every day? Do you enjoy it? Is it fun? Or do you do it because you feel like you have to? I know that is a lot of questions to start an article, but I want to make a point here, so bear with me just for one more question.
Why do we do PR reviews?
Most developers would say that we do reviews to catch bugs, but that is not it. Code review can actually be about way more than this. On pull requests, we are only seeing a part of it, essentially just a git diff , so you can catch syntax errors, but we can’t see how that interacts with the rest of the system just yet, so if reviewing a PR is not about catching errors then what is it about?
After a research conducted within real companies about pull requests, the three main benefits an engineering team can get out of reviewing PRs are:
- Knowledge Transfer
- Increased Team Awareness
- Finding Alternative Solutions
Code Review is the discipline of explaining and discussing your code with your peers and that goes a long way to becoming a better software engineer. It’s actually a communication resource that gives the opportunity to discuss real implementations.
That’s why we need to not only prioritize it but also get better on it so we can extract its full value.
Getting better at it
There are two main things you can do to help your team with code reviews, two rules of engagement, the first rule is what you can do as an Author of a pull request and the second is what you can do as a reviewer.
As an author
If the content is king, context is God - Gary Vaynerchuck
This quote was about social media but it can also be applied to code reviews, if the content is your code then the context is the “Why” you are doing it.
Provide context is the main thing you should do as an author of a Pull Request, not only the context behind the “Why” you’re doing that change but also any technical context that might help other folks down the road, like the techniques you used, or maybe explaining a design pattern you choose. Let the reviewer know what you have learned in the process of doing this code, that’s a great opportunity to share knowledge.
As a Reviewer
The main rule for a good review process is
Ask, don’t tell.
Feedbacks on code reviews tend to be received much more negatively than when done face to face. So we need to overcome this if we want our feedback to be received in the right way.
One way of doing that is to offer compliments, I do recommend you to do it, make sure to point out the good stuff and the things you have learned from a PR.
The key to overcoming the negative tone a code review can have is to ask questions instead of making demands. Questions have the power to start healthy conversations.
Comments like “Extract this into its own function to avoid duplication” only provide two alternatives to the author, she either changes it or replies starting what looks like an argument. But instead, you could rephrase that for “What do you think about extracting this into its own function to avoid duplication?”, that opens up a bunch of possibilities to actually start a conversation, maybe she has thought about it already, maybe that is not possible, or maybe that is actually a good idea and she will embrace it and change the code.
“What do you think about” is a great conversation opener for code reviews.
Wrapping up
Code reviews can be a great tool that can empower you and your team, but as any tool, it needs to be used properly otherwise it can make people extremely uncomfortable to pitch in their ideas and to contribute more to the codebase.
Keep in mind that Code Review is so much more than finding bugs, it actually helps your company to spread knowledge and your developers to get better at their jobs.
Last but not least, this article was hugely inspired by a great talk of Rails Conf 2015 called Implementing a Strong Code-Review Culture so make yourself comfortable to check it as well and get more in-depth explanations and examples.