What is code review?
Code review is a process to ensure that bugs and errors are caught and fixed before they reach production. This very often requires the participation of developers who are not directly involved in implementing the particular part of code that is being reviewed. Code review is part of a bigger quality assurance process to ensure that the final product performs exactly as expected.
Apart from checking source code for bugs, code review is a great way to check the code base for the presence of best practices and the absence of anti-patterns.
Why does code review matter?
People often have different opinions on all sorts of things, especially when it comes to code, and that is totally OK! But when it comes to the codebase used in a production application, you will want to ensure that all developers on the team speak the same language regarding naming policies or architecture patterns.
Why does this matter? Imagine two developers, Alice and Bob, writing an app together. Alice loves using a global singleton string, also known as the Singleton pattern, for state management, while Bob prefers using the State pattern. They work on different parts of the application committing their changes directly to the shared repo.
Then Alice leaves the project for a few weeks on vacation, and now Bob has to fix a bug in a feature she implemented. He sees the global singleton string and, confused, changes it to the State pattern implementation, just as he did with all of the features he has implemented before.
Unfortunately, doing so requires twice as much time to fix the bug, so Bob quickly becomes annoyed and disappointed.
Had they implemented a code review process from the beginning, Alice and Bob would have identified variances in style much sooner. What they needed was a collaborative workflow that made sense for both parties.
What should a code review cover?
Let’s look into the basic outline of what a successful code review should cover and what elements of the code the reviewer should be paying close attention to.
When performing a code review, the person reviewing the code should focus on the following:
- Code style
Repercussions of No Code Review
Why is code review so important? What will happen if there is no code review or too much code review?
1. The potential to introduce high-risk bugs.
Code Review is primarily intended to find bugs in code. If there is too little code review, or no code review at all, some bugs will likely pass to production unnoticed. Bugs can cause low-risks, like faulty UI, or high-risks, like security breaches. Without code review, the team has very few instruments to predict and evaluate such risks.
2. Inconsistent codebase.
As in the example with Alice and Bob, people tend to prefer different patterns and code styles and may use different approaches to state management. The difference in approaches may slow down further development and code support. Every time you need to implement something new or fix a bug, the developer will have to take the time and mental energy to learn a new process, further slowing the process.
3. Bus factor.
Bus factor refers to the risk measurement associated with not sharing information and capabilities among team members.
So, if only one person knows how a specific part of the project works— the one who wrote it—and said person leaves the project, you will probably have to perform another code review, or even rewrite the code all together.
Too Much Code Review
When it comes to having too much code review, there are very few risks associated, but there are a few cons, so to speak. Having an abundance of code review can cause delays in production and may cause developers to focus too much on satisfying the code review, rather than fulfilling high-level business goals.
At the end of the day, it’s important to find a golden median. Evaluate the risks associated with limiting code review if you have to prioritize faster code production.
Code Review Checklist
Code review is, above all, a communication process. And like any other, everyone involved should feel respected for the process to be efficient. So there are some simple rules to follow to make your code review helpful and nice, while also providing useful feedback.
If you are the person performing the review, consider the following code review checklist:
1. Explain your opinion.
When pointing to an error, add a bit of explanation about why you think this should be viewed as a mistake. This will make you sound confident and will also help the code’s author to not make similar mistakes in the future.
On the other hand, it could be you who is wrong. Explaining where you’re coming from will help encourage a discussion to find the best solution if there are any variances in opinion.
2. Include examples.
Sometimes, it’s hard to understand a message like: “change it according to the guidelines”‘ or “use the X pattern.” What might be obvious to you could be a complete riddle for someone else.
Give a brief example of what the final result should look like in your opinion to help the author understand your idea.
3. Point out specific problems.
“I don’t know what’s wrong with this code, but you can do better” isn’t very helpful. Tell the code’s author exactly what’s causing the issue. Is it memory management? Is it code style?
Make sure to provide helpful details, particularly if the resolution will require further investigation by the author. Most of the time, when code isn’t provided in a satisfactory state, the better solution doesn’t just pop into the reviewer’s mind. It’s OK to request further investigation by the author, but you should provide some direction.
Code Review Tips
People work more efficiently when cooperating. “Two heads are better than one,” right? This is precisely the reason why, as a reviewer, you should try and sound friendly. Maintaining a cooperative tone of voice helps the team concentrate on solving the issue at hand, instead of escalating conflicts.
Here are some code review tips on tone of voice:
- Avoid blaming.
- Don’t say: “you did a bad thing”; say: “it’s not great to do it that way, and here is why…” After all, it doesn’t matter who wrote incorrect code. What is essential is whether this code gets fixed. So concentrate on commenting on the code and not the developer.
- Code review is not a performance evaluation.
- Simply telling someone they’re not good enough won’t help them become better. Treat code review as part of an asynchronous pair programming process. You don’t tell your pair programming partner they suck at coding, do you? Instead, you help them fix mistakes. This approach works with code review as well.
- Be empathetic.
- Having code review comments full of criticism can be overwhelming, even if the critique is written as friendly as possible. Show some empathy and compliment good code when you see it! It can go a long way. When a developer has spent time and effort doing something valuable to the team and product, it’s worth noting!
- Be open to further discussion.
- Every code review comment should be discussable. You can proactively reach out to anyone involved in the process to elaborate on the matter or make sure your team knows how to contact you. A prompt call or even a couple of messages can save a lot of time, misunderstandings, and hard feelings.
Who should perform a code review?
One of the main questions when it comes to the code review process is who should do the review? Basically, there are two options:
- One designated person—usually a senior developer or team lead—performs code reviews for everyone on the team.
- Everyone on the team can perform a code review.
You can also think of something in between, like a designated sub-team for example, but it acts the same as the first option.
Code Review and Pull Request Templates
Pull request templates are helpful for implementing consistent code review processes across teams.
Here is where tools like the GitKraken Git GUI can really come in handy. If you’re managing your project’s branches with GitKraken, you can simply right-click on a branch from the central graph to access many options, such as pushing and pulling, merging, rebasing, or starting a Git pull request.
If you select the option to start a PR, the pull request modal will open. This is where you can set a PR title, description, assignee, reviewer, and a few more details. When you’re happy with what you’ve got, click Create pull request to see your PR available in the left panel, and your related hosting service.
GitKraken supports pull request templates for GitHub pull requests, GitLab pull requests, and Azure DevOps pull requests, and gives your team the ability to create a consistent code review process for all of your projects.
The pull request process is integral to successful code review, but establishing a good system can take time. Let GitKraken do the heavy lifting with built-in PR management and templates.
One of the most important parts of a code review is the Git pull request body. This also tends to be one of the most conflict-provoking parts of the code review.
Some people think the Git pull request title is self-explanatory, while others struggle to understand what “fix THE BUG” is describing. To avoid arguments, you can work together as a team to find a code review checklist that includes the most important information to be written, evn for seemingly obvious pull requests, like a list of affected features for example.
Your Git pull request template can have a pre-made body with hints on what has to be stated one way or another. You’ll find very quickly which parts of the code review checklist are most useful for the reviewer, and if any are frequently left empty.
You can read more about Git Pull Request Templates, and below is an example of what a typical PR template might look like.
Cross Code Review
Team involvement is crucial in a successful code review process. Cross code review might be your savior if your team struggles to identify a single approach towards review.
First, you will set a number of “approves” needed for a Git pull request to be merged, and then you can unleash your team’s code reviewing power!
Pull request templates in GitKraken can help the cross code review process. When you’re creating a new pull request in GitKraken, a pull request template drop-down menu will appear in the PR modal. This allows you to choose from templates you have already created for one of your repositories so your team can quickly fill in all of the information needed on the designated pre-drafted template.
It can be helpful to let anyone on your team review every pull request. Elaborate on the priority of a pull request and then let people decide what to review according to priority. For example, you could have a Slack channel where urgent PRs are upvoted and the one with the most votes has to be reviewed, by literally anyone who wants to, by the end of the day.
Working with different parts of code will make the team more conscious about what’s happening in the project. Working with various team members will quickly set the new predictable norm for code styling, pull request completion, etc. Cross code review is one of the most effective ways of in-team communication and knowledge exchange.
In addition pull requests templates and filters, GitKraken has more team features that will take your code production to the next level.
GitHub Code Review
Also possible with GitKraken is the ability to manage GitHub pull requests directly in the GUI, making GitHub code reviews quick and easy for everyone on your team.
The interactive GitHub pull request view in GitKraken allows you to edit pull request title, description, reviewers, assignees, milestones, and labels. You can also leave comments for the person reviewing your code.
For those conducting the GitHub code review, you can even approve the PR or request changes, all without having to navigate to GitHub.
ProTip: double-click on a branch name in the bottom right of the GitHub pull request view and GitKraken will automatically checkout the branch and open the graph so you can get straight to work!
Minimizing the Effort of Code Review
Code review often grows weaker with time and too often is abandoned as a process forever. If this is what happened to your team, it doesn’t mean that code review doesn’t work or just doesn’t work for you. One of the reasons that code review can fail for a team is because the process took too much effort from reviewers, and that burden can quickly become overwhelming.
So how can you minimize the effort associated with proper code review?
CI/CD and Automating Code Review
One part of the code review process that takes significant effort is testing. Can you approve the merge of some code if you aren’t sure the code compiles?
A typical process may require that before tapping the “approve” button, you clone the Git branch, compile the code, and then maybe even test the code. This is especially time-consuming for big projects, which can take a long time to clone and compile. You could have spent that time writing useful code, but instead, you’re waiting for someone else’s code to compile…
The solution is easy: don’t do manual testing! Seriously. Let the continuous integration (CI) handle the job before you even come to the pull request for code review. This will require some extra automation code, but, hey, this code is going to save you and your team hours of work!
What can be tested in a CI code review routine?
- Whether the code compiles.
- Whether the code builds.
- Whether the code can be archived correctly and deployed (Docker, we’re looking at you 🐳).
- Whether all of the dependencies integrate smoothly (especially if versions were changed).
- Unit tests and other automated testing passes.
Code Review Tools
Equipping your team with the appropriate code review tools will set you up for success and will help eliminate unnecessary work and developer burnout.
The GitKraken Git GUI initially helps streamline the code review process by providing better visibility into what your team is working on. The central graph in GitKraken displays your branches and commits in a way that makes sense, so your team can create better code with fewer errors.
When an entire team is involved in making and reviewing pull requests, it can get difficult to keep track of all the potential changes coming into the project. You and your team can easily organize your reviews by filtering pull requests by who the PR was opened by, assigned to, awaiting review, and more.
GitKraken also integrates with tools that can be helpful for integration testing during code review: GitHub Actions and GitLab CI.
The integration options offered by GitKraken will ensure your team provides a consistent code review process across all projects, and you can quickly find the PR you’re looking for.
You may also want to invest in a static code analyser for style guide violations and antipattern detection.
Code Review Best Practices
- Do not overcomplicate code review.
- Code review is not a tool to make code perfect. Code review is a tool to help developers avoid silly mistakes that are hard to notice. Concentrate on helping deliver a good project at a reasonable time, rather than perfecting the codebase.
- Be nice to your teammates; facilitate a friendly culture of code review.
- Comment on code, not on the author, and provide helpful feedback instead of “👎 / 👍 ”. If code review causes arguments on your team, work on facilitating a friendly culture. Create pull request templates and book meetings to discuss PRs.
- Review only what can’t be checked automatically.
- Minimize the effort needed to review a Git pull request by automating as much as possible. Request code review only for those features that cannot be checked automatically like architecture, readability, etc.
- Don’t do solo code reviews unless there’s a good reason for it.
- Bus factor is not the only argument against the solo code reviews. Team involvement is crucial if you want code review to assist knowledge exchange. Encourage cross review: it is less time-consuming and a lot more fun than the designated reviewer(s) model.
- Invest in code review tools that alleviate work from your team.
- Don’t make your team do all the work associated with code review. Invest in tools that make the process easier so your team can focus on writing quality code which will take less time to review.
GitKraken will improve and expedite your team’s review process so you focus on code quality, rather than digging through pull requests.