Demystify Code Reviews
Enhancing Code Quality Through Effective Reviews
In the fast-paced world of software development, ensuring the quality, security, and maintainability of code is more critical than ever. One of the most effective tools we have to achieve these goals is the code review process. Not only do code reviews help catch bugs and improve code quality, but they also foster knowledge sharing and collaboration within the team
Why We Do Code Reviews
Quality Assurance
Other engineers who are more familiar with the technology can help identify potential bugs that you might have missed. While you can write unit tests for your code, allowing others to perform code reviews provides an opportunity to catch any oversights. If the solution you’re attempting has been tried before without much success, this is also a chance to discuss it if it wasn’t caught during daily stand-ups. Besides quality, this is also a good time to review security and compliance of your PR.
Engineers may also comment to ensure consistency by checking if the PR follows the general code guidelines set by the SRE team or your team. Some of these guidelines can be enforced using linters and dependency cruisers, but some architectural decisions may still need human attention.
Knowledge Sharing
Having a PR for code reviews can be used for knowledge sharing for both the author and the reviewers. The author can share their idea in the form of a PR as an RFC for other members to review or as a reference for an implementation that other teams may need. Essentially, if you don’t want to write documentation, you can share your PR around. For reviewers, you might also provide insights or propose other solutions as you may know the technology, library, or overall codebase better.
Doing code reviews also gives you an opportunity to mentor junior engineers, helping them write better code and get onboarded to the codebase quickly. You can provide suggestions on what can be improved or discuss why they approached the problem in a certain way.
What Should Code Reviewers Do
Constructive Feedback
Everyone has different experiences and thinking processes. They will make decisions based on the information and knowledge they have. As a reviewer, if you think there are better ways to do things, focus on the code, the architecture, or the design—not the code author. Explain your thought process, invite the author to express theirs, and be polite and kind to foster a positive review culture.
When providing feedback, try to be clear and give actionable suggestions instead of saying, “This is bad,” or “We shouldn’t do this.” To guide others, you should provide suggestions that people can act on or directions where they can improve. Giving comments without explanation can potentially cause emotional damage.
Sample feedback you can give:
• I suggest we name this variable to be more descriptive like transaction instead of x.
• This function contains multiple logics and conditions. Should we break it down to improve testability and readability?
• It seems this component doesn’t handle loading and error states. Might be better to add them for better UX?
Scope of Changes
This is mainly for the PR author, but as reviewers, you could suggest making the PR smaller so it’s easier to review and ensure this PR includes the changes mainly for the said ticket. Smaller PRs allow the reviewers to quickly understand the context and keep the scope within manageable boundaries, which should help merge the PR much more quickly instead of sitting in the review queue for a long period of time.
Bias and Subjectivity
There are situations where it is fine to use either technology or library, but people may have their own opinions on which one they prefer. Try to keep your reviews and feedback as objective as possible and reduce personal bias in the review process. We want to make the code better, not just what someone thinks is better. Throughout the process, reviewers should encourage collaboration and discussions from both parties. This should ultimately help create a more welcoming culture in the team, allowing everyone to express themselves.