The ‘soft’ aspects of code review: A more human approach

As a software engineer, I’ve always appreciated the importance of code review in the development process. I’ve spent a decent part of my career working on the open-source code review tool Gerrit and educating engineers around efficient code review processes. I acknowledge it as one of the most important parts in large scale software development.

It’s during the code reviewing process that your source code is meticulously examined by your peers, with the goals of identifying and rectifying potential issues. This is the time to share knowledge and ensure future maintainable code quality.

However, over time, I’ve come to realize that the primary focus on technical considerations often overshadows the human aspects involved. In this blog post, I share my insights on the softer aspects of code reviews and how being aware of these aspects can lead to a happier and more effective team.

Embracing vulnerability in code review

A common sentiment among developers, and especially junior ones, when it comes to code reviews, is discomfort. Code, in many ways, reflects the programmer’s knowledge and thought process, making it feel deeply personal. So of course, having your work scrutinized in the open can be unnerving.

Remember, though, even the most seasoned developers make mistakes, and no one ever stops learning. Yes. All developers make errors. Code review isn’t a personal critique but a fantastic opportunity for knowledge sharing and continuous improvement. An engineer that states he/she does not need to have his/hers code reviewed, that is an engineer who has stopped learning.

I will talk more about the knowledge sharing parts, but acknowledging your peers’ possible discomfort will make for a much better code reviewing experience and your team’s well-being.

Beyond bug hunting

Code review is not solely about finding bugs or issues in the code. I would argue that it is not even the most important part of the process. In fact, knowing this is so important that a common recruitment question is just that: “Why do you implement code reviews in your workflow?”. If you can answer this question with more than “Well. Finding bugs!” you may have an ace in your sleeve for any future employment interviews.

That being said, did you know that performing good code reviews is one of the most cost-effective ways to spread knowledge in a team? The author of a new code change wants to share knowledge about the changes happening in the codebase. The reviewers want to impart their domain knowledge.

Performing code review the right way fosters a collaborative environment, leading to a deeper understanding of the codebase and improve team efficiency, far beyond the pure bug hunting parts. It’s an investment in the development team’s future.

The art of kind code review

As with any form of feedback, it’s essential to approach code reviews with empathy and respect. These are your colleagues, your teammates and sometimes your friends. So instead of pointing out faults with statements like, “This suck! Why would you do that?” opt for a more constructive approach. Use phrases such as, “I suggest…” or “What do you think about…”. Always explain the reasoning behind your comments, provide guidance rather than dictating changes.

And refrain from just pasting 45 lines of code into a comment and going “Do this instead!“. By doing this, you, the reviewer, have not really shared your knowledge and reasoning. The author is none the wiser and if you think about it, is this a particularly nice way to share? If you don’t like someone’s cooking, you can help, give pointers and share insights, but you won’t (hopefully) bring out a different cake to replace the one your host(ess) baked.

And don’t forget to commend good practices. A positive comment like “Nice way to solve xyz”, can go a long way in fostering a healthy code review culture.

Resolving disagreements in code review

Inevitably, there will be times when the reviewer and the code author don’t agree completely. Now you need to solve your differences. Long debates can waste time and resources, leading to delays and friction. If a disagreement persists, lean towards the code writer’s approach. A code review comment does not need to be accepted as a final truth.

However, if the stalemate continues, consider bringing another reviewer on board to provide a fresh perspective. And then, you go with the judgement of the reviewer you brought in. No further discussions are needed.

Streamlining the code review process

A common culprit for extended integration times is the time spent waiting for someone to examine your code change.

Seeing your code change waiting for days for a review (and going stale in the process) can be a frustrating and disheartening experience. Therefore it’s vital to prioritize any incoming reviews as much as possible.

Encourage open dialogue about what works and what doesn’t in the review process and find a way that suits your team best. An efficient review process not only ensures code quality but is vital for team morale and productivity.

In conclusion, while technical acumen is necessary for effective code reviews, the softer aspects play a crucial role in the process. By fostering a culture of respect, openness, and continuous learning, we can make code reviews a positive and enriching experience for all developers involved.

If you’re interested in learning more about my thoughts on code review, Axis Communications recently sponsored a guest lecture at LTH (Faculty of Engineering, Lund University) where I delve into both the technical and human aspects of code reviewing.

Lecture on youtube (swedish)