How to: Competent Code Reviews
A review that does not find defects is not a poorly done review
This blog post is based on the paper “Competencies for Code Review” by Pavlína Wurzel Gonçalves, Gül Çalıklı, Alexander Serebrenik, and Alberto Bacchelli presented at the 26th ACM Conference on Computer-Supported Cooperative Work and Social Computing (CSCW).
Given enough eyeballs, all bugs are shallow.
— ES Raymond
Two heads are better than one and that is why software developers review each others’ code before it can go into production. Code reviews are now a ubiquitous software engineering practice that aims to ensure that new code merged in the code base has good code quality and maintainability. On top of that, code review is a collaborative activity that supports transparency and knowledge sharing in the team. In our study we do not look at the effectiveness of the code review process in finding defects but rather at individual reviewer’s performance and aim to provide a frame for answering the question:
Was this a thorough and competent review?
There is limited understanding of what skills and competencies developers need to perform reviews well and that they develop through doing code reviews. Companies, open-source projects, and developers recognize the value of code reviews for both learning and professional growth. When onboarding new team members, code reviews are especially beneficial. Senior and seasoned developers can use them as a platform to share insights about best coding practices, team processes, company standards, and the overarching code architecture. However, reviewers also encounter challenges during code reviews. These include dealing with intricate code modifications, subpar code quality, limited clarity on the proposed changes, and miscommunications or conflicts.
The TOP 5 Competencies
Code review is a complex activity that requires developers to exercise their technical as well as social competence. Developers need to be able to understand the change sufficiently well to perform a sound technical review. But they also need to be able to discuss these specialized topics effectively, being considerate of their colleagues’ work, communication needs, and goals. Understanding these competencies can assisst us in identifying where developers need help to improve code reviews but also what activities need to be supported by code review tooling. An overview of all the competencies we identified through literature search and interviews with experts is available in the article itself. Here, we focus on presenting the main insights.
We performed a study that aimed to identify which competencies reviewers need to demonstrate when performing reviews. We have used existing competency frameworks for software engineers and interviewed experts in the field to arrive at 27 of competencies relevant to perform code reviews well. We asked 105 developers to help us rate which competencies require more attention when designing training or assessing code review performance.
The competencies that are frequently used in code reviews are also the ones that developers consider more important for effective code reviews. These are the top 5 most important competencies according to developers:
- Developing a mental model of the code change
- Evaluating whether the implementation fulfills requirements
- Evaluating the correctness of the code
- Giving constructive feedback
- Communicating in an understandable way
The technical competencies are an essential baseline to perform code reviews. Developers need to be able to catch functional and maintainability or usability issues in the code. But what other skills do they need to demonstrate to do a sound technical review? A good understanding of the change assists reviewers in finding the issues in the code. Reviewers need to create a so called mental model of the change — that is how reviewers represent the code change in their mind. This also includes how the change is related to the rest of the code base. Developers utilize their other abilities, like effective usage of programming languages, paradigms or software engineering practices that lead them to better see familiar patterns in the code. Knowledge of the code base can also be helpful to better understand the changes in the system’s architecture. Developers’ ability to find relevant information within and outside the code base — in the programming language documentation or other external resources — contribute to reviewers’ potential to create a detailed and accurate model of the code change and compare that to the expectations about code quality or change requirements.
Social competencies are as important as technical competencies to perform code reviews. And while developers feel confident in their technical competence to perform reviews, they are less confident about the social interactions. Code review is an exchange in which the reviewers give feedback to the author, but they also represent a bazaar of ideas exchanged between colleagues. Therefore, code review is as much about giving constructive feedback as well as receiving it on both ends — author’s and reviewer’s. As developers have to be able to support their ideas, they need to be willing to discuss, accept, and act upon ideas of others. As receiving feedback can be difficult or tiring at times, developers also need to be able to handle their own emotions and sometimes deal with interpersonal conflicts. Among all the areas we discussed, they feel least confident in handling these conflicts.
Research invests a lot of effort in improving the technical, defect-finding, part of the reviews (even though this is changing). However, developers are clear — they also need support to communicate in a more clear, effective and constructive manner.
Reviews are integral to a developer’s job. However, with many tasks at hand, developers strive to balance their time between reviews and other responsibilities. They have to manage their review time effectively. Additionally, not all reviews carry the same importance. Reviewers must assess each review’s scope and type, and prioritize giving feedback that is most relevant and meaningful.
What’s next?
Code reviews can be a great exercise to use when hiring for roles required to perform code reviews, when helping managers and team leads to mentor and give feedback to their colleagues, or when boosting novices’ knowledge of coding standards. Competencies are a great way to design training or performance assessment activities. These activities can include scenarios in which developers need to use certain competence to solve the task. Our paper provides a frame to select the competencies to be used for such activities — either by focusing on the generally more important ones or the ones that the developers themselves identify as their own opportunity to learn and improve. For example, developing a mental model of the code change is a crucial competency. Developers can be tested on how well, quickly, or accurately they develop mental models of the reviewed change and whether their competence to do so improves over time and allows them to identify more functional defects.
Equally importantly, if a team struggles with code reviews, they might need to have a discussion about where developers need support to either develop their competencies to a better level or about what do they need to use their competencies efficiently. We can design team activities to improve tracking and allocating review time or test different approaches to feedback and learn to be constructive in the safe environment that training provides.
Last but not least, code review tooling can address these comptence needs and find design solutions to support developers in review time tracking, prioritization or building accurate mental models of the code change.
If you want to be successful, don’t seek success — seek competence.
- J Vasudev
