Requesting, Giving, and Receiving a Great Code Review
Let’s say we have two software developers — we’ll call them Itchy and Scratchy. Scratchy has been hard at work on a new feature, and he’s feeling ready for a break, so he submits a PR for Itchy’s review.
Itchy is busy, and doesn’t get around to reviewing the PR for a few days, by which time Scratchy has moved on to other things. When Itchy does start his review, he discovers that in his haste to be done, Scratchy didn’t put much information in the PR. Itchy is annoyed. The review takes him longer than it should, and he gives Scratchy some very blunt negative feedback, which doesn’t exactly make Scratchy excited to dive in and fix bugs. Scratchy ignores Itchy’s comments, and the feature launch is pushed back.
This is an extreme case (complete with silly names), but this scenario plays out on a smaller scale in almost every software team. When we don’t take the time to request and give feedback in a structured and respectful way, we risk alienating colleagues and missing learning opportunities, not to mention shipping buggy code to production. We’re not fans of any of those outcomes at Grio — so we have a few simple best practices that we adhere to as code authors and reviewers.
Best practices for requesting a code review
As a code author, you’re responsible first and foremost for providing your reviewer with all of the necessary context upfront. That means including the following information in your PR:
- Acceptance criteria, i.e., a clear description of the expected result of running your code
- A clean and clear commit log
- A list of steps or tasks that need to be performed before testing the code (e.g., downloading data)
- A list of steps for testing the code
It can be helpful to list all of these requirements (along with anything else your team has found useful) in a PR template, which can be used as a reference when requesting a code review.
The code author is also responsible for determining who should review their code. Usually, this will be the person who is most familiar with the relevant product, feature, or technology; in some cases, it might make sense to ask more than one person for a review.
Finally, for the code review process to be productive, the author needs to remain humble and open to feedback. Very few of us enjoy having our hard work picked apart, but we’re all human, and we all make mistakes! As an author, it can help to remember that you and the reviewer both have the same end goal — namely, high-quality software.
Best practices for giving a code review
There are several things that you can do as a reviewer to ensure that the code author gets what they need from your review — and that you don’t get frustrated or overwhelmed in the process. In particular:
- Review the PR as soon as possible. This allows the author to move forward quickly, and also means that the code will be fresh in their mind if you have questions.
- Before you dive in, make sure you understand the aim of the PR and have enough context to review it. If you’re missing something, ask!
- Review deeply. Run all the tests and code, and point out possible weak points and opportunities for improvement, not just must-fix mistakes.
- Pay attention to tone and phrasing in your comments, and think about how you would react to them as an author. And remember that not all comments have to be constructive — praise great work where you see it, too!
These practices are simple, but they can go a long way toward ensuring bug-free releases. They’ll also help your developers learn and collaborate more efficiently, and they’ll keep everyone happier and more productive throughout the code review process.
