The subtle art of giving great code reviews
February 06, 2020 · 5 minute read
How to ensure your feedback is interpreted as constructive criticism
Written by Jason Barry
Co-founder & Head of Product
Peer code review is the biggest and best thing you can do to improve the quality of your code.
So much so, that in the book Code Complete, Steve McConnell gives real-world examples of the dramatic impact code review can have:
- AT&T reported a 14% increase in developer productivity and a 90 percent decrease in defects after they introduced reviews.
- Jet Propulsion Laboratories estimates that it saves about $25,000 per inspection by fixing defects at an early stage.
- Aetna Insurance Company was able to decrease its development resources by 20%.
Having a second pair of eyes give your work a once-over can help prevent mission-critical bugs from entering into the wild. And you can learn a thing or two along the way.
A code review happens once a developer has submitted a contribution to the project.
This is known as a ‘pull request’, and you can read a detailed definition and learn how to use them effectively in our previous article.
Before this contribution can be added to the project, other team members will review the code, checking for issues, suggesting improvements and ensuring overall product quality.
This code review can take place whether the team feels most comfortable. It could be comments on Github, a chat on Slack, via Skype or in person.
The benefits of code review are obvious — you’ll discover bugs, improve code quality and build better projects, too.
But the major benefits of code review are about people.
Sure, you can use testing, but the statistics seriously speak for themselves — the average defect detection rate is only 25% for unit testing, 3% for function testing, and 45% for integration testing.
Therefore, your code reviews must never be entirely automated. Instead, try incorporating some of these ideas into the process:
- Sharing Knowledge: When programming, there are often several ways to solve a problem. Reflecting on why this particular approach was chosen reveals hidden knowledge. For example, the reviewee might have a different understanding of the architecture of the application, a superior knowledge of the technology being used or is lacking a key skill — all of which are opportunities to share knowledge.
- Better Estimates: When estimates are wrong, code reviews are an opportunity to see where the hidden complexities or difficulties were. This leads to more accurate estimates in the future.
- Mentoring: Code reviews can uncover areas for improvement and self-development, which is invaluable to any reviewee. It can also be valuable for the reviewer, who will learn by teaching others.
- Check requirements: Code reviews are the perfect opportunity for agile teams to return to the user story acceptance criteria and check that requirements are met. For added insight, involve stakeholders, designers, and product managers with review tools like FeaturePeek.
Nobody likes being criticized, especially by their fellow team members. For a code review to be great, the reviewer must balance being positive with avoiding code defects.
The first step is to remove the stigma from reviews. Bugs should not be seen as negatives, but instead as an opportunity to teach, fix bad habits and to improve code quality.
This means that the number of errors produced by each team member should not be tracked, nor used in performance evaluation reviews.
The next step is to reframe the code review as a coaching opportunity. Instead of harsh criticisms, employ the Socratic method. The most effective way to do this is to encourage self-evaluation by asking questions, paving the way while helping them discover it for themselves. Just like this:
|Critical Feedback 🙀||Constructive Feedback 😸||Outcome 😻|
|"Why doesn't this have test coverage?"||"How could more test coverage benefit us as a team?"||Improved understanding of test coverage|
|"This function is terrible / complicated!"||"How could we improve this function to make it simpler?"||Future functions will be easier to understand|
|This doesn't match the design!||"Looks good, but it's different from the design — was there some complexity in implementing the design as specified?"||Identify issues with requirements or skills|
If one of your reviewers is struggling with constructive feedback, coaching or relationship training might also be appropriate — the goal is to always keep your team feeling motivated and ready to do their best work!
Positive peer pressure is a powerful tool. As developers know that their peers will see their code during the review process, allow them to improve their code before submitting it. After all, we all want to look good in front of our team members!
So, follow these steps to ensure that each reviewer is doing the best they can:
- Agree a definition of ‘good code’ with your team. This might include formatting, commenting, security considerations or other considerations unique to your industry or team. Use a linter if you aren’t already. It should also include a summary of how to make a pull request that can be reviewed quickly — see our guide to authoring better pull requests.
- Include a ‘good code’ checklist in every pull request. The submitter must complete this pull request.
- The reviewer should check the code to ensure this checklist is accurately completed.
Code reviews are blockers — until a review has been completed and the code merged, the next stage cannot be completed. If issues are identified, the developer might need to redo work, slowing development further.
Resolve this issue by agreeing to complete code reviews within a certain amount of time. For example, you could agree to have the code review completed and pull requests merged within 2 business days.
Of course, a goal without a plan is just a wish. Therefore, make plans to ensure success, such as:
- Allow your reviewers to prioritize reviews over other tasks when required, and never penalize them for missing deadlines as a result.
- Assign more reviewers as needed.
- Reduce the number of approvals required. Some teams require 2 reviewers to approve before merging — if this is a blocker for your product, ask yourself: is this always necessary?
- Measure the time taken to complete pull requests and seek feedback and suggestions for improvements regularly.
Now you know how to give great code reviews that improve code quality and improve team productivity, your next step is to automate and systemize where possible. Try adding FeaturePeek into your review workflow to reduce the friction of doing peer code reviews today.