9 Minutes
Why should you do code reviews as a team?
‘WTF? What’s that?’ is something you often hear when working with systems that have been around for a few years and have many developers working on them.
**The goal of having regular code reviews as a team is to minimize the ‘WTF?’ moments in the long run by building a common understanding of good code.
Nobody writes perfect code. Everyone learns over time. Code reviews as a team give everyone the opportunity to learn from and with each other. Each developer has a different perspective and experience. This leads to a diverse understanding of what ‘good code’ actually means in a specific case. Discussing these different perspectives and developing new solutions and ideas together is the key to building a common understanding for good code in the long term.
But…
’…I can just do my code reviews in GitLab.’ In principle, code reviews using GitLab are useful and meaningful to find problems, get a second opinion and share knowledge. Unfortunately, this way only helps to a certain degree to build a common understanding of good code, to discuss problems and issues and to develop new solutions. For code reviews to work well via GitLab, a common basic understanding of good code and thus code reviews in the team are essential.
**A code review by a colleague may deliver 80% of the result for the specific piece of code, but it will not promote understanding in the team why this or that variant is better in this situation. In other words, our ability to write better code in the future only improves to a limited extent.
’…I don’t know anything about this. What can I contribute?’ Look at the code and ask questions. Everything that seems strange or is hard to understand is worth a question. Even if you see an unknown construct, just ask. Often such questions lead to important discussions where everyone can learn something.
How do code reviews in teams work?
In order to make code reviews in teams pleasant and productive for all, there are a few rules that must be followed by everyone. This concerns the preparation, the selection of code, the specific process and the etiquette.
How do participants need to prepare?
Everyone comes to the meeting prepared. In order to use the time in the meeting productively, all participants must have prepared their questions and comments about the code.
Each participant takes 30-60 minutes preparation time, to read through the code and write down their questions and suggestions for improvement. Less than 30 minutes is usually not enough to seriously engage with the code. More than 60 minutes usually does not lead to better results.
How do authors have to prepare?
The author sends out an invitation with a short explanation in advance Which classes / methods should be reviewed? Where is the best entry point? What should be achieved business-wise with the changes? Are there any open points/questions? It is extremely important to set the right frame and give the reviewers priorities.
Do not review finished code. It happens again and again that the author wants to do everything right and therefore chooses a piece of code that is already finished. This is NOT a good idea.
-
It hurts a lot to have to make changes and adjustments to this code again. Usually there is no time planned for these changes.
-
It is less bad if your own code - which you know is not ready yet - is criticized than a piece of code that you have put an incredible amount of effort into and that you actually believe to be good. Experience shows that no matter how much you’ve polished the code yourself, there will be plenty of feedback.
-
You can bring questions to the review as author yourself. ‘I have the following problem and I’m not quite sure what a good solution looks like. What do you think?’ This automatically leads to constructive discussions.
In short, don’t spend three weeks tinkering with something and polishing it unnecessarily. Also, allow for time to incorporate the suggestions later.
Less than 400 lines of code per review. It is important to limit the amount of code to be reviewed, otherwise the quality of the review and the discussion will decrease. With more than 400 lines of code, the ability to find more bugs and issues decreases sharply [1]:
Figure 1: Error density in code reviews [[1]]
How does the meeting work?
**The group of participants should be manageable and limited to 4-7 people.**The more people participating in a review, the less open discussions will take place.
A neutral person presents the code and moderates the session. It is essential that the author does NOT present the code and moderates the session. A neutral moderator is much better able to watch speaking times and will not get caught up in emotional discussions so easily. On the contrary, s/he will intervene if a too intense discussion arises.
The meeting is limited to 60 minutes. This sometimes feels like stopping in the middle of a discussion, yet it has been proven that there is a sharp decrease in effectiveness afterwards [1].
The author takes notes. Participants can, of course, still send him or her their comments separately. Usually it is best to discuss only the most important issues during the review only. Small things like typos etc. can simply be sent to the author afterwards.
**The author starts with a short introduction of the code and explains his/her thoughts and open points. Afterwards, each participant presents their 2-3 most important comments or questions about the code in a maximum of 2 minutes. The purpose is to get a first impression of the most important issues. There is no discussion at this stage.
**The moderator goes through the most important points ** The moderator then goes through the most important points and moderates the discussion on the different topics.
**If necessary, it is a good idea to go directly into a refactoring for individual issues and to change the code ( as an example).
What else is important?
Mutual respect, no sarcasm. That should go without saying. We all want to learn something. A lot of work has gone into the code. Therefore it is only fair to show the author the necessary respect.
Always say something genuinely positive about the code first. We often tend to dwell too much on the problems and inconsistencies. In most cases, however, there are things that have been solved very well. It is important to make these explicit too.
Conclusion
Code reviews in a team are like workouts. At first, no one really feels like doing it and you wonder if you should do it at all. Once you have begun, it starts to be fun. Suddenly the hour is over and you are disappointed to have to stop. Everyone is glad they did the review and talk about how good the discussion was for a few more days.
We are all only human and have an incredible amount of work to do. But it’s worth sticking with it and trying a few times, even if it feels strange at first.
