How does communication affect code reviews?

An important aspect of successful software projects is good communication, both how to establish it and how to keep it alive. Hence, a couple of software development practices have emerged in support of achieving this goal. One such practice is code reviews and how to use them to your advantage. Please note that this is just one view and there is not a single way of how to apply it. In fact, many practices are highly dependent on the context. This article attempts to present the author's view on how to use code reviews and how they should be embedded in the software development methodology to maximize desired outcomes.

The goal of code reviews

The purpose of code reviews is to make sure that the overall code health of your code base is steadily improving over time, including but not limited to catching issues, security problems and bugs before they can cause problems in production. Another aspect that is sometimes overlooked is that code reviews are also a tool where engineers keep improving how to do code reviews, reflecting upon technical solutions and viewing changes in the context of the code base and desired outcomes. Hence, they are an indispensable tool to ensure that engineers can learn from each other.

However, doing good code reviews requires practice and effort. Sometimes the benefits of investing a significant amount of effort are not clear or even discouraged due to how things are handled within or across teams. Common pitfalls may include but are not limited to:

• fostering code ownership instead of removing it
• establishing hierarchies instead of encouraging each other
• making decisions based on opinions instead of data

But when done right, code reviews are a fantastic tool to create a safe and open learning environment that encourages people to share context and motivates them to contribute to a project.

Especially in a remote setting, it is important to make decisions and the process of preparing the decision as explicit as possible while trying to keep explanations short and precise. This helps people to align on various topics during software development. But documented decisions serve as a reference as well and can later be used to guide future decision making supporting open communication. Sometimes this kind of activity does not get the attention it deserves or is done by a small group only, which may cause a lack of transparency and consequently reducing the effectiveness of code reviews when facing non-trivial or unforeseen situations. Although we strive for being as welcoming, friendly, respectful and patient as possible, people also have believes and spent a lot of time and effort contributing to their projects. So, it is not uncommon that team members do not agree with each other all the time. And while disagreement should not be an excuse for poor behavior and poor manners, it is equally bad not to talk about these incidents openly. After all, each team member sits in the same boat trying to achieve the same goal.

Another important aspect easily overlooked is that teams sometimes do not communicate enough among themselves. It is quite common that people misinterpret written sentences, even when the meaning carries the complete opposite intent. Suggestions can be easily misinterpreted as criticism, or people may feel attacked when a reviewer uses a clumsy phrasing. These and similar incidents can lead to situations, in which team members actively ignore each other or try to do work behind each other's back (exclusionary behavior is not acceptable). The solution is very simple though. Sometimes it does wonders to simply state things out in the open to facilitate conversations. Code reviews can't fix broken communication and distrust.

Questions such as "what is readable code?" or "what is simple code?" may spawn many discussions that can keep teams busy for months as there are no "one-size-fits-all" answers. To address this issue it is usually a good idea to start documenting broadly agreed standards and best practices to avoid that reviewers enforce standards on their own. With respect to standardizing things, it is of utmost importance to emphasize that these are living documents that are shaped by a team for a team. Then code reviews may become a fantastic tool to achieve both helping new team members to better understand the code and helping the team to write simple code. If people do not believe in a common set of rules or views, alignment beyond a shallow level (at best) is not possible.

Knowing some of the many communication pitfalls, helps to better deal with them once you encounter them.

I suggest to read a couple of further blog articles about mindful communication in code reviews and to invest some time to think about potential effects of good and bad communication. Here is a short list of articles about code reviews, I recommend reading:

• https://www.holloway.com/g/remote-work/sections/mindful-communication
• https://kickstarter.engineering/a-guide-to-mindful-communication-in-code-reviews-48aab5282e5e
• https://stackoverflow.blog/2019/09/30/how-to-make-good-code-reviews-better/
• https://www.freecodecamp.org/news/a-zen-manifesto-for-effective-code-reviews-e30b5c95204a/

References

[1] "Experience with inspection in ultralarge-scale development", Russel, 1991