The neglected value of code reviews

Technical leadership is much more active on a day-to-day basis in code review than in writing code. The reviewing process is often considered less important or purely bureaucratic, when in reality it is central to any technology company. A large part of an organization’s technical direction should be done through code review, not meetings or presentations, and for this to work efficiently, engineering tools must be used. 

Code review is an excellent strategy for training, coaching, and mentoring professionals. To begin with, code review can be seen as a continuation of the onboarding process for newcomers joining the company. With careful and detailed code reviews, it is possible to teach them:

• What the company’s processes are
• How the system is organized
• What details need more attention

The code review process is extremely important for mentoring newcomers, especially when working remotely. By reviewing code attentively and carefully, the company’s technical leadership professionals can convey the technical direction for building the systems that will provide stability and enable innovation. 

Of course, this doesn’t mean that individual contributors at the highest levels should spend all day reviewing code for systems that are commodities and have little strategic relevance. They may even do that to gauge the quality of work at the base of the pyramid, but the bulk of their activities should concentrate on the most relevant and strategic projects for the company at the time.

Care for the code generates efficiency because it’s easier to correct a problem during the review and testing process than after the system is already deployed. Incidents are also avoided along the way if whoever is responsible for the code review feels comfortable asking for modifications whenever necessary, which only happens when the whole process is ingrained in the company’s culture. The review can’t be seen as a task to be done in a hurry, just to get the code into production as fast as possible. 

By reviewing code attentively and carefully, the company’s technical leadership professionals can convey the technical direction for building the systems that will provide stability and enable innovation. 

Regardless of whether a person writes text or code, mistakes are bound to happen, and the person who made the mistake usually can’t see it, no matter how carefully they re-check everything. In texts, there is a process of editing and then proofreading, and with code, it’s the same: a second and even a third pair of eyes greatly reduce the likelihood of errors going unnoticed, even if several tests have been carried out. The code reviewer brings a fresh, different outlook that can catch a bug or suggest a modification that will make the software better.

Rules for effective code review

The clearer the guidelines and standards are, the easier it is to review the code, because anything that falls outside the standard becomes obvious and is not open to questioning. When there are no standards, the review is much more subjective. 

If a tool already integrates formatting, for example, the reviewer won’t even need to comment or correct the way the code is formatted. Even if the guidelines aren’t integrated into the tool, just the fact that there is a standard in place removes the need to comment. It is enough to say: “It doesn’t follow the standard,” and no further explanation is required.

There is an established etiquette that must be followed when reviewing code. The review must be respectful, and although speed is not the main objective, agility also counts. First, it must be clear to everyone that the review is not personal. Both the reviewer and the reviewee must treat it as constructive feedback, not a fight of egos. The person doing the code review shouldn’t compete with the person writing the code. 

When those “diminisher” leaders—in the terminology of Liz Wiseman and Georg McKeown in the book Multipliers— reject at first glance the code they were supposed to review, and then rewrite it in their own way, developers get frustrated and, over time, may leave the company. 

Code reviewers must be professionally mature to realize that they are not competing with whoever wrote the code, but rather:

• Looking after the quality of the code
• Applying the company’s architectural standards
• Preventing incidents from happening in the future

Both the person who asked for the review and the reviewer must keep their comments polite and objective, with the awareness that the purpose of their exchange is to improve the code so that everyone wins later.

There is an established etiquette that must be followed when reviewing code. The review must be respectful, and although speed is not the main objective, agility also counts.

On the more practical side, it is non-negotiable that any request for a code review should come with the corresponding tests. As soon as the reviewer receives the request, he or she should open it, take a quick look to check that the tests have been included, and give an initial response to whoever wrote the code, opening a line of communication. If the reviewer sees that there are no tests, that something is not up to standard, or that for some reason it is not directed to the right person, the request should be immediately returned, so that no time is wasted, and an appropriate submission is made. 

The existence of tools to conduct these iterations increases the effectiveness of the process. Comments from both sides are public and should be read by the other people involved in the project, so the learning process gets multiplied. The tone of the comments, both on the side of the reviewer and the reviewee, must be polite and clear. And if the thread gets too lengthy at some point, a live chat can sometimes be the best communication tool. When the disagreement can´t be easily overcome, it’s worth asking a third party to mediate.

Code review goals

In addition to checking the correctness and unambiguousness of the code, the reviewers should have broader objectives in mind; after all, this is how they put the company’s technical guidelines into practice. In the review, they assess whether:

• The proposed change is being made in the right place
• It actually solves the problem
• The problem is the right one to be solved
• It is a necessary investment
• The design of the change is scalable
• The change ties in well with other elements of the platform
• The code is resilient to failures and instability
• It won’t create dependencies that lead to technical debt
• The proposed interfaces are extensible and intuitive
• There is correct documentation to avoid maintenance problems later
• The new code has been written in the spirit of facilitating further testing in future modifications
• There are mechanisms to prevent potential incidents in production, as well as systems for alerting and reversing changes in the event of an emergency
• There are performance problems that the change may cause (something that happens more often than one might imagine)

When code-reviewing, leaders can check in real time whether the platform mindset is being applied and can take action if it is not. They also ensure that the code is clear, readable, and standardized so that any developer in the company should be able to read and understand it, even many years later. Finally, they are helping to build a mindset in the organization to avoid technical debt; plan short-, medium-, and long-term horizons; and foster innovation by thinking in terms of platforms.

Valuing code reviews

To establish a strong code review culture in the company, it needs to be prioritized, and this prioritization needs to be reflected in people’s performance and compensation reviews. If the system only values new features that have been put into production, the importance of code review goes unnoticed, and there is no incentive to do it. How can the company reward a person who spends 80% of their time carefully reviewing the code written by other engineers, ensuring that the business priorities are being translated into systems?

The emphasis on code review must be aligned with the parameters used for career progression, and other less tangible initiatives can reinforce the process. First, set the example: if the company’s top technical leadership reviews code and makes their comments publicly available, this sends a clear message to the rest of the engineering team of how important code reviews are. 

Leaders’ personal involvement is one mechanism for recognizing achievements and establishing company culture. Strategic objectives must be integrated into both performance reviews and more informal incentive methods.

Another reason to value a code review culture is to share responsibility when an incident occurs. The person who reviewed the code cannot be seen as the one who simply authorized the change by pressing a button, but rather as a partner in the development of that code, and someone who can get involved in solving any problems that may arise.

The habit of exhaustive testing makes it possible for teams to feel more secure in opening their code to external contributions, be it from within the company or even outside it, in a truly collaborative way.