Code reviews best practices: A Beginner’s Guide

You’ve probably already heard of code review. Would you like to understand better the principles of code review, the benefits it brings, and the essential points to watch out for to ensure that it takes place in good conditions? That’s what this article is all about!

What’s a code review?

The principle of the code review is to have one or more persons reread parts of the source code written by another person. This is part of a process of continuous improvement of the code and its quality. There are several objectives when setting up a code review:

1. Identify bugs or problems as early as possible. Keep in mind that the later a bug is found, the more expensive it is to solve. As the code review usually takes place a few days after the code is written, the cost of resolution will be under control.
2. Produce a clean and maintainable code. A quality code is, above all, a code that can be understood by anyone other than its author. A source code is more often read than written. The review ensures that other people understand the code and will be able to rework it later.
3. To increase knowledge of the code within the team. Rereading the code on which you are not directly involved also allows you to appropriate other parts of the code. A 2016 study conducted at Google highlighted precisely this since developers had on average reread twice as many files as the number of files in which they had modified the code after one year.
4. Ensure that the norms, standards, and best practices defined in the team are followed. This is an excellent way to re-explain certain concepts, especially if you are rereading the code of someone who has just joined the team.

In 1976, Michael Fagan theorized and studied the benefits of code review processes, highlighting gains in productivity and bug detection. Indeed, as good practices are better understood and problems identified earlier, it is easy to imagine less time spent fixing bugs after the fact.

As with any practice, code review can be counterproductive if it is poorly executed or misunderstood by the team. For some people, the term “review” may suggest a control or monitoring modus operandi to make negative criticisms of the developers’ product code. Therefore, it is very important to clarify and share the objectives with the whole team and highlight the continuous improvement process.

Team spirit and culture will strongly impact the way code reviews are conducted.

The prerequisites that we consider indispensable are those defined by the 10 Commandments of Egoless Programming, taken from Jerry Weinberg’s “The Psychology of Computer Programming” (1971). Although their presentation will be the subject of another article, remember that these commandments aim to improve collaboration between developers by detaching one’s “ego” from the code produced.

The code is collective property. Each developer must be open-minded, humble, take a step back from his code, empathize with others, and know how to accept if other people propose better decisions than his own. This sounds like common sense, but their application is far from systematic!

Each team will adapt the frequency of code reviews according to its needs and context. For some, they will take place systematically each time a development branch merges (Pull/Merge-Request). For others, they will be more punctual (once a week) on more central parts of the code. In all cases, there are certain best practices to follow, both for the submitter and the reviewer:

• Limit the size of the magazine to 400-500 lines max. This is already more than enough code to be proofread, and since the objective is not to remain superficial but to go deep into the code, it is best not to submit too much code. Beyond that, the proofreader will start to get tired and will naturally become less vigilant.

• For the author who submits a review, a checklist of points to check must have been validated: the code compiles, unit tests are OK, continuous integration is green, good practices and conventions have been reread… Here we are paying attention to the person rereading the code!

• For the proofreader, a checklist (readability of the code, architecture, compliance with conventions, etc.) must have been drawn up beforehand and shared within the team. The scope of the review will be clearly defined and, and you’ll avoid discussions that could go too far beyond that. On the other hand, it also avoids the abuse of “nitpicking” in the comments, generating frustration for the authors.

• The reviewer’s comments should be constructive and suggestive. Rereading code calls on everyone’s know-how, and the way in which comments are made is very important: knowing how to compliment work well done, offering suggestions and not imposing corrections, pointing the finger at the code and not at the person, showing empathy… We avoid saying loud and clear in the open space “Who wrote me filthy code?”.

If the team’s pattern is that the “Tech Lead” profile is the only person to proofread the code, it is also relevant to invite each person to participate as a proofreader. After all, everyone can contribute their vision and new ideas, whether junior or senior. And even if you are a senior, you should always strive to improve, and no one is infallible!

Code reviews: communication exercise for high-performing teams

A related objective of the journal is to strengthen communication within a team and to facilitate the development of developers’ skills. It is a very good exercise in dialogue and sharing that reinforces cohesion and well-being within the team. Reviews are also very revealing of each person’s “soft skills”. The success of a project depends mainly on healthy and productive exchanges between each stakeholder.

A study conducted at Google in 2015 highlighted the key performance factors of a team. Beyond criteria such as experience and qualifications, the main factor that emerges is that of psychological security.It reflects the comfort and ease with which developers are comfortable talking openly about problems in the presence of other people in the team and taking risks and initiatives. If there is trust in a team, each person feels freer to act without fear of the reaction of others, and especially without the fear of failure. Practicing code review also means establishing this psychological security which has so many advantages for a team!

Finally, we mentioned above that code review increases the knowledge of the code within the team. Have you heard of the Bus Factor? This is the number of people beyond which your project cannot continue in a viable way if they are hit by a bus. It is a way of illustrating the concentration of expertise within a team. By inviting each person to reread code they have not written, and thus to appropriate other parts of the code, this knowledge is better distributed within a team.

So, you’re ready for your first code review?

Still doubt the benefits of code review? If it is applied properly, this practice brings obvious gains to the whole team. Our Promyze platform offers precisely the Craft Workshop format, a collective review format to focus on the definition of best practices. Based on team discussions and decision-making, the Workshops meet all the objectives of the code review while consolidating team cohesion.