For more thoughtful code reviews
The code review is a difficult process for some developers. It can involve discussions, feeling of being judged and create stress in the team. It’s a process where you put your hard work in the defendant’s chair and see it being judged by several people. Furthermore, it is very hard to not be emotional being on this position and I don’t think it’s possible — at least not for me.
There are some good guides on how to create a cohesive pull request and how to decide if adding or not a comment. For this article, I want to share my experience on trying to make the code review process more thoughtful and use it as a tool to build trust and grow, rather than create fear.
Be kind
There are some lines of thinking that suggest that we shouldn’t be sentimental about code reviews and our goal is to be truthful with the code and architecture. So, when you receive a comment like “This is wrong. Do x instead.” or “Why are you doing x instead of z?” we should be completely detached. I don’t agree with this approach for two reasons:
- We spend time and effort in implementing our solution, and I don’t believe people want to deliberately write bad code. It’s okay to not feel good when you receive feedback saying that what you did is wrong;
- There are more empathic ways of giving the feedback. Maybe for you, it’s fine to receive this feedback, but the concept of empathy is the ability to take on another’s perspective, not how you feel about it.
It’s also important to notice that several comments are suggestions rather than absolute truths. It’s not difficult to see heated discussions about topics that are clearly personal preferences rather than something that will impact performance, scale or stability.
Personally, I prefer giving a more “curious” approach to start a conversation rather than saying there is right and wrong:
- What do you think about using x instead of y?
- Would it make sense to use x because that would avoid z?
- I don’t have full context about this feature, but does x make sense here?
Embrace the “annoying” comments
Sometimes we receive a comment which our first reaction is “what the hell is this person thinking?” or “I’m not going to re-write my code because this person wants to”. This is natural, it’s a defensive mechanism when we feel judged. Instead of quickly reply and starting an argument on why you are right and why they are wrong, my recommendation is to take a time and reflect about it. The more annoyed you felt, the more time you should take. Take a walk, go grab a coffee, think more about it.
In my experience, most of the time I felt defensive and quickly replied, after a few minutes I realized the person had a good point. In some cases, I realized that I didn’t understand the comment and made defensive assumptions that blocked me from learning and improving. Generally, I regretted my impulsive response.
You are not your code
This is easily said then done, but the code you produced does not define you. It’s not because you received a few comments or didn’t notice that there was a better way of solving the problem that you are a bad developer. There are several reasons that could cause it: you are not familiar with that part of the code, you had to cut some corners for hitting a deadline, or you might not know that there is an API that already does exactly what you are trying to achieve. One of the main goals of the code reviews is to learn.
Define a codebase guideline
Recently, we noticed that some of the code reviews we were doing were repetitive. There are some rules that a linter does not cover, but we like to enforce in our codebase. One solution to reduce these comments and make the process smoother was to define a codebase guideline containing the “common rules” that we follow but were not documented anywhere.
The guidelines are available in the repository itself and can be updated at any time by submitting a new pull request (and having the team review). This live documented helped reduced comments and also is a great way to onboard new developers in the team, making everyone more confident.
Avoid leaving a dozen of comments
A lot of developers have a phase where they want to be right rather than being a team player. I’m not proud to say I also had mine where I left dozens of comments in a code review and though I was doing a great job. I wasn’t. That was my ego speaking louder than my willing to help. The message I was trying to give was: “I know more than you — look how many flaws I found in your work”.
Today, if I notice during a code review that the amount of comments per line of code is disproportional, instead of submitting the review, I have a sync with the developer. There is a reason behind this: the developer didn’t understand the assignment, the top-down pressure is too intense that they are rushing the work, or I’m not understanding what is being achieved there. Leaving a ton of comments is not going to help in any of those cases, it will create more stress.
Guide the review
Another thing that creates some friction for everyone is not having the context needed to evaluate the code. In my experience, this can lead to some issues like reviewers not paying attention to the code or focusing on the wrong things. When this happens, we lose the opportunity to improve our code and learn from others. Having a clear pull request description, adding images and videos, and making sure that the change is concise can help reduce the animosity.
My recommendation is to also leave comments in your own change explaining why you are going by this direction and even ask for suggestion. If you feel that your change can start a discussion, start the conversation by giving context:
- I’m using x over y because it will be easier to fetch the information by doing that. Please, feel free to suggest alternatives here.
- I went with this different implementation because I believe that x and y will improve perform better than z. What do you think?
- I’m not very knowledgable about this API. Is there a better way to use it?
Guiding the review not only will help others, but will start a conversation by making you vulnerable, and that’s a good thing. We are basically stating: “I’m doing my best here, but I think we can improve somehow. Could you be part of it?”. Which leads me to the next point.
Be vulnerable
This can be applicable in several contexts in the professional life, and code review is not an exception. Start from the assumption that we can learn from others and that people are acting in good faith, can help us grow a lot. So, when you put yourself in a position that you let people help you, the effect cascades.
I love helping other people in technical problems. It’s the favorite part of my job, and I feel a lot of joy doing that. However, the team needs to be open and welcoming to new ideas and be helped. And for others to feel this joy, I need to be in the position to receive help. Then both sides feel good: the person that doesn’t carry the burden of “I must know everything” and the other than can provide help and feel heard.
Final thoughts
For some teams, code review is a difficult process that can turn into a stressful experience and bottlenecking not only the productivity but also the team’s vibe. If used thoughtfully, the code review can be a powerful moment not only to ensure code quality but also to strengthen the personal connections and improve the culture. And a team that feel comfortable together grows much more than you can imagine.
