30 Proven Code Review Best Practices from Microsoft

Which code review best practices do companies such as Microsoft, or Google follow to ensure great code review feedback? How do you stay productive while doing code reviews?
In this article, you learn 30 code review best practices for code reviewers and for code authors.

As this article is an in-depth resource, let me give you a quick overview of the 30 best practices for code review first.

This article first appeared on michaelagreiler.com.

Code Review Best Practices Overview

The benefits of code reviews rise and fall with the value of the code review feedback. If done correctly, code reviews can help to ensure a high-quality code base. However, if teams are not aware of and do not follow best practices for code review, developers may experience several code review challenges. In the worst case, reviewing code can slow your team down.

I have been researching and working with teams at Microsoft for several years. Through several large scale-studies, we discovered several best practices that help teams during code review to stay productive and boost their code review value.

If you are new to code review, let’s look at a typical code review process. You can also skip this introduction and jump directly to the first peer code review best practices.

A typical code review process

A typical tool-based code review process starts when the engineer prepares the code for review. Then, she selects relevant reviewers for the code change. The reviewers are notified. The reviewers then inspect the code for defects, readability, and maintainability and give feedback on the code. The code review author works on the feedback until all parties are satisfied. Then, the code is merged with the common code base.

To ensure that the code review process is smooth and does not become a nightmare, it is important to understand code review challenges and which code review best practices you can follow to overcome those.

The main code review challenges are:

• not getting useful feedback,
• not having enough time to do code reviews,
• code reviews taking too long, causing long waiting times.

The code review best practices below help counteract those challenges by making the job of the reviewers as easy as possible. They also help the reviewer focus on providing valuable feedback.

Code review best practices for code authors

In a code review, there are two different stakeholders: the code author, who asks for feedback, and the code reviewers, who look through the code change and provide feedback. As a code review starts with the author, I explain the code review best practices for code authors first.

1. Read through the change carefully

The first code review best practice is to read carefully through the code change before submitting the code for review. There is nothing worse than asking several developers to look through the code and give feedback on issues you could have fixed yourself.

This wastes everyone’s time, and it might make you look bad. For future code reviews, developers may also be reluctant to review your code.

So, ensure you use a code review tool or a diff tool that can highlight what changed between this and the previous version. Because these tools show you the code differently and highlight the parts that changed, it makes it easier for you to review your code yourself before sending it out.

Often you will see changes that you actually forgot you made or missing issues highlighted you should fix before asking somebody to review.

The best time to fix issues is before you send the code out for review.

The best time to fix issues is before you send the code out for review. Click To Tweet

2. Aim for small, incremental changes

As a developer, you should always strive for small, incremental, and coherent changes. This code review best practice helps when working with code revision tools, such as git or SVN.

Small, incremental code changes are also a crucial code review best practice, as other developers must be able to understand your code change in a short amount of time.

10 lines of code = 10 issues.

500 lines of code = “looks fine.”

Code reviews.

— I Am Devloper (@iamdevloper) November 5, 2013

If several changes with different purposes happen within one code review, the task of code reviewing becomes more difficult. This also decreases the ability of code reviewers to spot problems with the code. In several studies, we see that the value of the code review feedback decreases with the size of the change under review.

You also want to make sure the changes are coherent. Rarely are code changes too small to be sent out. It happens, but not that often.

The quality and value of code review feedback decrease with the size of the change. Click To Tweet

3. Cluster related changes

Another code review best practice is to cluster related code changes. Imagine you plan to add some new functionality, fix a bug in another function, and refactor a class. Then, each of those changes should be a separate code review. This way, you ensure the purpose of the code change is clear to the reviewers. A clear purpose makes the reviewing job much easier and increases the feedback value.
In case you realize your code change grew too large, you can use a technique called stacked pull requests to split the pull request into several smaller ones.

5. Provide a code review description

One excellent investment of your time during code review is to write a description of what this code change is all about. With this note, you help the code reviewers to understand the purpose of the code change and also why you changed it. This code review best practice speeds up code review time, increases the quality and value of the feedback, and improves code review participation rates.

Code reviewing isn't a puzzle. Help reviewers focus on key issues by describing the code change. Click To Tweet

Interestingly, in our studies, we observed that developers really appreciate code change descriptions. They actually wish that more people would write descriptions. Counterintuitively, we saw that the same developers that wished others would prepare code review descriptions did not always include descriptions themselves.

One reason for this is that when you write the code yourself, you are so involved with the code that you fall for the expert blind spot. This means you think the code change is self-explanatory. The fact is, it is not.

To ease the work of writing code review descriptions, you can use pull request templates to pre-populate the pull request description already with the information that is relevant to be provided.

And if you do not help the reviewers to understand the code, they cannot provide valuable feedback.

So, write the note, even if it just says: “Updated the API endpoint to comply with security regulations”.

How much easier did the job of reviewing the code just get with this note? Remember, code reviewing isn’t a puzzle.

Even if the code change seems trivial to you, add a description so reviewers know what to expect. Click To Tweet

6. Run tests before submitting a code review

Take the time to run tests for your code change. Testing isn’t only a best engineering practice, but it’s also a code review best practice. Because testing your code ensures that the code actually works before you ask for feedback.

In addition, it shows that you respect the time of the code reviewers. It is not only embarrassing to send out code that obviously (as the tests show) is not working as expected, but it also kills everyone’s productivity. So, run the tests first!

And don’t forget to write new tests or update existing ones so that you cover the added or changed functionality reasonably.

7. Automate as much as possible

As one of the main challenges of code reviews is taking too long, you better follow the code review best practices of automating as much as possible.

Use style checkers, syntax checkers, and other automated tools like static analysis tools to help improve the code. This way, you make sure that code reviewers can really concentrate on giving valuable feedback and do not need to use their time to comment on issues that can be found automatically.

8. Skip unnecessary reviews

You read that right. You can skip code reviews. Obviously, it depends on your organizational policies, but if they permit it, you might consider skipping code reviews for trivial changes.

But stop before heading out and telling your team you need no code reviews anymore. Skipping code reviews is only advisable for trivial changes that do not change the logic, such as commenting, formatting issues, renaming of local variables, or stylistic fixes.

Skipping unnecessary code reviews boosts your productivity. Click To Tweet

9. Do not select too many reviewers

You should select the right number of reviewers for your code change. If more than 4 people come to your mind who should review the code, I’d like you to stop right there. Because adding too many developers to code reviews does more harm than good. Also, this is a sign that your code change is too big.

The main problem with adding too many developers as reviewers is that each one of them feels less responsible for giving feedback. Another issue is that adding more people than necessary decreases your team’s productivity.

Some studies suggest the code review best practice of adding only two active reviewers. At Google, only one reviewer reviews 75% of all code changes.

For some code changes, you want additional experts, like security experts or developers from other teams, to look through the code. But, more often than not, two active reviewers are just fine.

Many code review tools allow notifying developers without making them mandatory reviewers. This ensures that they stay in the loop and are aware of what is happening but removes the obligation for them to comment on your code.

Clarify review expectations

Every person that is added to the code review should know what you expect of them. Should they look for defects?

Did you add them because they should familiarize themselves with the code base? Or, did you add a developer from another team that uses functionality of the codebase and you want them to look specifically at the API?

Everytime you add a person as a reviewer, you should know and communicate your motivation. This code review best practice ensure that reviewers focus on the right issues, and helps fight bystander apathy.

10. Add experienced reviewers to get insightful feedback

Another code review best practice is to add experienced reviewers. Studies have shown that the most insightful feedback comes from reviewers that have worked on the code you are going to change before. They are the ones that give the most insightful feedback.

How often a reviewer has already reviewed code influences the ability to give useful feedback. Similar, experienced and senior developers tend to give better code review feedback.

But, be mindful of the workload of senior engineers, as they tend to be added as reviewers a lot. In addition, adding only developers that know the code already creates knowledge silos and hinders knowledge dissemination.

Developers that changed or reviewed pieces of the code before give the most valuable code review feedback. Click To Tweet

11. Add inexperienced reviewers for knowledge transfer

One of the code review goals is training and learning, so do not forget to include junior developers. Junior developers might not find the most bugs during code reviews, yet, code reviews will help them ramp up and learn from the senior members of the team.

Also, do not forget to add people that are not familiar with the code base but that benefit from the knowledge to allow knowledge dissemination. Having several people on the team that are familiar with the codebase helps if developers go on vacation or even leave the company. But be strategic about it. Make a plan on how many people should cover and know about certain parts of the codebase, and then use code reviews to disseminate the knowledge.

12. Notify people that benefit from this review

For some people, like project managers or team leads, receiving notification about code reviews (without being actually required to do the code review) is beneficial. But, you have to make a conscious decision on whom you gonna notify. Not everybody really cares or should care about your code review.

Notification fatigue is real. In addition, specify your expectations so that developers know if they are notified because they should review the code, or just to keep them in the loop. Some code review tools allow specifying roles explicitly.

Do not add everybody to the notification list. Only add people who actually benefit from the information that a code review is in the process.

I have seen teams where each team member was added to each of the code reviews of the extended team by default (+70 people). This practice is like adding nobody to the list. Or, in the worst case, you have several of your engineers spending their time looking through hundreds of code reviews to figure out if it’s relevant for them.

13. Give reviewers a heads-up before the review

A really effective code review best practice is to let your co-workers know ahead of time that they will receive a code review soon. This code review best practice reduces turn-around times substantially.

So, let them know a code review is coming their way as soon as possible.

Giving people a heads-up that a code review is on its way can speed up review time. Click To Tweet

14. Be open to the suggested changes

Receiving unexpected comments or feedback might make you tense and defensive. Try to prepare yourself mentally and work on your ability to be open to suggestions and different viewpoints. Always start with the assumption that the reviewer had the best intention.

If some feedback made you uncomfortable, try to sort things out as soon as possible. Sometimes it is a good idea to have more personal face-to-face conversations to resolve some issues.

15. Show respect and gratitude to the reviewers

Code reviews rise and fall with the team’s feedback culture. As a code author, it is a code review best practice to show gratitude and value the received feedback. Make sure to carefully consider the reviewers’ feedback and communicate throughout the feedback cycle.

Tell the reviewers which actions you took and which decisions you made because of the received feedback in a respectful manner.

Code review rises and falls with the quality of the team's feedback culture. Click To Tweet

But, creating a great feedback culture is a two-way street. Naturally, code reviewers influence the culture a lot. So let us look closely at this best practices for code reviewers.

Code Review Best Practices for Code Reviewers

Being asked to give feedback on a code review is an honor, so you want to make sure you know how to give valuable code review feedback.

During code reviews, you can not only demonstrate your skills and knowledge but also mentor other developers and contribute to the team’s success. Nothing worse than investing time in code reviews and not getting valuable feedback.

16. Give respectful and constructive feedback 

Even though it reads like a no-brainer, code reviews do put the code author in a vulnerable position, so you must be considerate of that.
Your job is to give constructive and valuable feedback but also to do so in a respectful manner.

Especially when you use a code review tool and give feedback in a written form, please reflect on how and what kind of feedback you give. It is just so easy to hurt someone’s feelings – especially in written form. Too often, time pressure might make you give a sloppy answer that can be misinterpreted.

17. Talk in person if necessary

Code review tools and chat tools allow us to communicate with our peers in an asynchronous and effortless way. But, there are quite a few situations where proper human interaction, either face-to-face or via voice/video, cannot be beaten.

Complex issues, for example, can be much more efficient and positively resolved once you hop over to your colleague or call her and discuss it personally. The same holds true for contentious issues or sensitive matters.

Maybe it is a better strategy to write a private email or seek a personal discussion with the code author if you think you might hurt some feelings are make the engineer lose the face. So, whenever you face a complex issue or might hurt some feelings, rethink your communication channels and act accordingly.

18. Document code review decisions

Even though less traceable conversations, such as face-to-face or video calls, can make a big difference in team dynamics, it is important to document the discussion. It is a best practice to record and track the code review outcome for future reference by using traceable tools such as the code review tool.

The code review tool is the right communication channel for all simple matters, as it allows the whole team to follow along and enables them to look up decisions and understand code development after the fact.

Even if you prefer to do code reviews synchronously, take the time to put a few notes in a code review tool to let also others (or your future self) know the outcome of a discussion.

19. Explain your point of view

Let’s be honest; having your code criticized isn’t something the code author will enjoy. So, it is important that you are thoughtful and explain your reservation in a polite, constructive, and friendly way.

Explaining the reasons behind your feedback and the suggested changes not only helps the code author to learn and grow but also helps the author to understand your viewpoint. It also promotes an ongoing dialog with the author.

Tell the code author exactly what she has to do to get the change accepted by you.

If you criticize a code change, explain precisely what you expect so that you approve the code review. Click To Tweet

20. Make code review rejections exceptions

Especially in a company and closed-source setting, code review rejections should be a very rare exception. It is a significant red flag if developers cannot produce code that will make it into the codebase. The ideas of rejection stem from the open-source setting. Here, it is normal for outside developers might suggest changes that do not align with the vision or roadmap of the open-source project as they are not involved. Also, because everyone is allowed to submit code, it frequently happens that the submitted code is not in an acceptable state or of quality.

Both should not happen in an environment where people work closely with each other. Here, developers should know the roadmap, and the tickets they work on should correspond with the vision. Also, after an onboarding period, even junior developers should be able to write code that passes the internal code quality standards – at least after some constructive code review feedback. If this is not the case, project management and the learning culture need to be revisited.

21. Integrate code review into your daily routine

Some of the biggest challenges during code reviews, for both the code author and the code reviewer, are time constraints.

As a reviewer, you might find it challenging to take time out of your day to review the code of your peers. But code reviews can be very beneficial to you and the team if done in the right way.

To ensure you stay productive, structure your day-to-day business in a way that you set dedicated time aside just for doing code reviews. For example, plan to work on code reviews every day from 11 to 12 AM.

This way, you make sure you can account for the time for code reviews and also make it an expected activity for you and your team. This schedule will come in handy every time you have a reflection on your work progress or an evaluation of your work.

22. Reduce context switching as it kills productivity

Switching from one task to another is costly. Knowing you do not stop whatever you do every time a code review comes along your way ensures you can work more focused.

Which time slots work depends on your workload, the number of code reviews you have to perform, as well as on the time those reviews normally come in. In some settings, your team benefits from two (shorter) scheduled reviewing times, such as in the morning and before you leave the office. This way, your peers do not have to wait for your feedback too long.

Context switching kills productivity. So have dedicated code review times. #codereview Click To Tweet

23. Give feedback in a timely manner

It is not advisable to jump right into a code review whenever the notifications pop up because of context-switching costs. Still, it has several advantages for you and the code author to review the code in a timely matter.

It is essential to give feedback as soon as possible. Also, Google recommends fast code reviews in Google’s code review best practice guideline. This ensures that you do not block the code author by having them wait for feedback. Also, if the author has to wait too long, it becomes harder for her or him to remember the changes and incorporate the feedback. Remember, long waiting times are a number one code review challenge.

Being one of the first reviewers (especially if there are quite a few) also ensures your effort in looking through the code actually adds value. If you are the fifth person inspecting the code, chances are you will not add new insights anymore. If that happens frequently, implement the code review best practice for selecting fewer reviewers.

24. Consider the time zones of your peers

Nothing is more frustrating than if a developer in another time zone reviews your code at the ‘wrong’ time. But what is the wrong time? If you have a big time zone difference, the wrong time to review a change is the time that stretches the time zone differences even more.

So, as a best practice for code reviews, when designing your personal code review schedule, check the time zones of your peers. It might make a big difference for someone if you dedicate half an hour in the morning instead of in the afternoon to do code reviews, while for yourself, it might not be that big of a deal.

25. Have your team play along

Code review is a team effort. If it’s only you that looks at reviews in a timely manner or systematically with checklists, you are not getting the complete benefits of code reviews. Instead, make sure everyone on the team knows the benefits, challenges, and code review best practices.

Especially for scheduling and coordination, there are effective habits that are easy to learn but help with accountability and workload balance. For example, the “give-one-take-one” practice.

The “give-one-take-one” practice means that every time you send out a code review, you do a code review for your colleagues. If you combine this with the code review best practice of sending out small code changes to review, the team’s workload will be balanced, and code reviews done in a timely manner.

26. Review often, not in a big-bang fashion

Research shows you give better code review feedback if you review often and, therefore, fewer changes at a time. That means that you do not wait until several code reviews pile up to look through them in one go. Instead, you stick to your schedule and review one code review (or even parts of one if it is a larger code review) at a time.

If code reviews are too large and take too long, you can suggest the code review best practices for small, incremental, and coherent changes to the code review authors. Another approach is to ask the code author to split the review into smaller changes, for example, using stacked pull requests.

Give better quality feedback to code reviews by not letting them pile up. Click To Tweet

27. Focus on core issues; do less nit-picking

Your goal as a reviewer should be to help with core issues, such as bugs, architectural problems, structural problems, or problems that will lead to maintainability issues.

Obviously, if you see typos, badly named variables, or styling issues, you might also point that out. Still, this is not your main task, and understandably, over-discussing minor issues isn’t valuable to code authors. So, follow the code review best practice to focus on core issues, and show when you nitpick (for example, with the appreciation NIT).

28. Start by reviewing test code first

While some developers would not even review test code, you follow the latest research in code reviews that suggests that starting your review with test code is a good idea.

In fact, when you follow the best practice of reviewing test code first, you kill one bird with two stones. Test cases document the use cases of the code. Thus, they help you form a mental model of what this code is all about. This means you get a better understanding of the test code and can give more valuable feedback. In addition, it lets you focus on the test code itself. This way, you ensure your test code is also of high quality and covers the functionality in a reasonable way. Having a high-quality test code base is a great investment. It increases the maintainability of the code, decreases manual testing costs, and helps to reduce post-production defects.

29. Use code review checklists

Another code review best practice is to use a systematic approach for code reviews. A code review checklist can speed up and improve your code review performance. Instead of making one from scratch, download a ready-made list and customize it to fit your team’s practices and your needs. Be sure to look for a checklist that is tailored to your technology stack. You can also use checklists to focus on specific aspects such as accessibility or security.

In addition, code review checklists make for a great learning tool that helps you improve your skills. Having a code review checklist also builds a shared understanding within the team of what is important and reduces conflicts, disagreements, and prolonged discussions during code reviews.

To help you implement this practice, I reworked my code review checklist into a beautiful printable PDF version. This checklist is the highest-rated general code review checklist on GitHub, and today you can download it for FREE and make your code reviews more systematic.

30. Fight code review bias

Unfortunately, code reviews and especially judgments during code reviews can be clouded by bias. For example, a recent study at Google showed that developers that identify as women get more pushback during code reviews than peers that identify as men. Also, other studies look at how race, gender, ethnicity, and age influence the code review experience. And also, these studies find that pushback, code review rejections, and also the scrutiny with which reviews are performed are biased based on those factors. For example, a large-scale study on code review participation and acceptance rate in open source showed that code written by developers that appear to be black is more likely to be rejected than code written by developers who appear to be white. As such, make sure you are aware of the existing bias during code review and proactively take actions (such as reviews of reviews) to reduce bias, harassment, and prejudice in code reviews.

Summary of code review best practices

Now that you know 30 best practices for code reviews, I wonder how many of those you already implement in your team. Tell me your score, and also which code review best practices you haven’t adopted yet and why. You can find me on Twitter at twitter.com/mgreiler.

This article first appeared on michaelagreiler.com.

Updated on January 15th, 2023