With over 6,000 PRs reviewed, we can confidently say that reviewing code is one of the main practices at Carbonaut. It allows us to maintain high standards in product development while sharing knowledge within the team 🧠

Recently we also introduced Code Review as part of our hiring process, and the experience was better for both us and the candidates 🚀

After doing a few code reviews in our hiring process, we realized some developers are unfamiliar with it. We wrote this guide as an introduction to it, we hope it helps!

What is a Code Review?

Code Review is the process of peer-reviewing code before it is merged into the codebase and shipped to production. A developer can request a review by opening a Pull Request (PR) on Github (or other version control). The reviewer can view all code changes in the PR and request changes by commenting on specific lines.

While this practice is time-consuming and often slows down the release of new features in the short term, we still do it for over 90% of the tasks. Here is why:

Why do we do it?

When we first started doing code reviews at Carbonaut, our only goal was to maintain the highest possible standard for our codebase. However, after over 5 years of performing code reviews, we have noticed other benefits:

• Increased knowledge sharing within the team;
• Increased discussions and definitions of code standards and best practices;
• The codebase is kept clean, easy to maintain, and with fewer bugs;
• Fewer tasks going through with missing or wrong requirements.

It is important to note that sharing knowledge within the team and defining code standards are medium to long-term benefits. These benefits allow developers to fast-track their learning and careers, and ultimately improve the overall quality of the product.

Although the code review process is simple, if done improperly it can generate conflicts between developers or fail to take advantage of all the benefits mentioned above 🥊

To maximize success in our code reviews, we follow these simple steps and tips:

How to Code Review:

Before the review, it's important to understand that reviewing code is different from writing code.

• Writing code: focuses on understanding the codebase and making changes to it;
• Reviewing code: ensures the code changes follow code standards, meet the task's requirements, and are made in the best possible way.

With that in mind, let's do our reviews in four steps:

1. Context

Before requesting changes to the code, ensure that you have all the necessary information 📚

This may include task requirements, design specifications, API contracts, how to reproduce the bug, or any other assets that may need to be included in the final solution.

Make sure you understand what changes are expected for the product so that you can visualize your own solution. Doing so will help you provide better advice and identify edge cases. 💡

2. Change Requests

Now that you have all the necessary context, let's dive into the code changes 🤿

Remember, you are not only trying to understand the code, but also looking for:

• Code smells;
• Ways to improve code legibility;
• Areas where the code might break;
• Behaviors that do not follow the requirements;
• Refactors or changes that are unrelated to the task;
• Code that does not follow the project standards.

You should add comments on everything you believe can be improved, but make sure your comments are:

ℹ️ Informative: Help the developer understand why you are asking for these changes;

👤 Relevant: Not just personal preference;

🎯 Decisive: Make it clear to the developer whether it is a suggestion or a strong request.

3. Testing

After reviewing all the changes, you should have a good understanding of all the areas that need to be tested. Now, it is necessary to manually test the feature or bug fix and ensure it meets all the task requirements ✅

In addition to testing the usual requirements, we recommend trying to break the feature by using it in unintended ways. Stress test the application, both the API and UI, with unusual test cases and weird user behavior. Document all your findings, including screenshots and videos, and the steps to reproduce any issues.

With time and experience, you may feel that you can catch all the bugs and edge cases just by looking at the code. It's at this point that you might be tempted to not test the feature and rely only on the code review itself. Don't! Always test it!

👉 The testing will differ depending on how much automation you have, but it's crucial to always ensure that the feature is working as intended.

4. Wrap it up

We are almost there!

You can finish the review by writing an overview to the developer. This will be the first thing they'll see when opening the review, so make sure you provide a clear overview of how critical the changes are and which areas the developer should focus their time on.

Before finishing the review, we recommend ‘reviewing’ all your comments, making sure everything is crystal clear and the developer won't need to reach out for clarification.

And… you are done 🎉

Bonus Tips 🎁

There is so much more we could talk about Code Reviews, here are some tips worth mentioning:

Have Empathy

When writing a review, it is important to consider the developer's experience and workload. This should guide the way you write your code requests. Here are some tips to keep in mind:

• If the developer has less experience than you, write educational comments. Explain why the change is important and provide additional resources for learning;
• Clearly indicate when a request is optional versus mandatory;
• When reporting a bug, include screenshots, videos, and detailed steps on how to reproduce it;
• It is always good to receive a compliment when we do something clever. You can add those as comments in the review, or share them publicly with the team;
• Feel free to use gifs 🕺

Keep the Momentum

When you request changes in a PR, it often delays the feature a couple of hours or even days and can impact the team's productivity and momentum.

In some cases, you can mitigate this issue by taking a different approach. For example, if your requests are mostly cosmetic or have a low impact on the product, you can:

• Create follow-up tasks for these requests and allow the feature to be deployed as it is;
• Fix it yourself and inform the developer about your changes. Remember to request the developer's permission before doing so.

This decision will depend on your team and project deadlines.

Automate, automate, automate!

Use static analyzers, linters, and automated tests to catch repetitive mistakes before they reach the review process. This saves time and effort and allows the reviewer to focus on things that matter, instead of having to focus on styling issues, variable names, untyped vars, etc.

Smaller is Faster

Smaller PRs are easier to read and review. It also has a higher chance of going through without change requests. If you are getting very extensive PRs it means your tasks were not broken down properly, or the developer included unrelated changes.

Prioritize Review over Coding

Don't let the PR hang in there waiting for a review 🥵

If you take too long to review, the coder will have a harder time remembering the context when they get back to it. In most cases, the task stays waiting for a review for longer than it took to implement it. Prioritize it and do it ASAP!

Final Thoughts

There is much more we could discuss about code reviews, but we hope this serves as a good starting point.

Remember, there is always room for improvement. At Carbonaut, we still have open questions about code reviews that need to be answered, such as:

• "Should we do code reviews for all tasks?"
• "How can we make it even easier for developers to document and maintain best practices with their peers?"

Let us know if you see areas where we can improve this guide, or suggest other topics you would like us to cover next.

If you are considering implementing code reviews on your team or want to discuss product development, we offer free consultations.

Thanks for reading through!

Resources

A lot of our ideas on how to improve our processes are from Refactoring.fm. We highly recommend checking their article on Code Review.