Why is code review such a challenging experience, and what can we do to improve it?

"Brutal", "minefield", and "frustrating" have been the words that most people used when describing their experiences with code review, which is not the word used in the title of this piece. However, why is that? Why is code review such a challenging experience, and what can we do to improve it?

Although code review is an essential part of software development, it can also create significant friction, anxiety, conflict, and wasted time and effort if not done correctly, which is often the case.

How can we enhance our approach to code review? Is it possible to conduct code reviews with kindness, gentleness, humility, and compassion? What kinds of comments are valuable for #improving #code and building #trust and safety with our #colleagues? How can we focus on the positive aspects of code while also handling bruised egos and making our points without causing enmity?

The life and times of a changeset

To begin, let's discuss what code review is and when it typically takes place. To illustrate this process, we can use the example of three professionals: Bob, Jane, and Isla.

In a given organisation, the typical workflow for code review involves an engineer, such as Isla, writing code, or working with a partner like Bob, and checking it into GitHub. Isla can then create a pull request, also known as a merge request, for approval by someone on the team, such as Bob, who may be a senior member or a maintainer.

Some teams may push changes directly to the main codebase, and may periodically pull from it into a release branch to create versioned releases. Regardless of the approach, there is generally a step where the changeset must be approved.

During the approval process, Isla will review the code by reading it and likely making #comments or asking questions about it. This review process typically leads to a conversation among Isla, Jane, and Bob, resulting in a few modifications before the merge is ultimately approved.

Pair reviewing

It's worth noting that in organisations, the conversation surrounding code review doesn't necessarily have to occur through a version control software itself, such as comments on a GitHub pull request. In fact, the most effective way to conduct a review is by speaking directly with a colleague, which allows for much higher-bandwidth communication compared to text-based feedback.

This is why it's important to engage in pair reviewing in addition to pair programming. For instance, Isla and Bob could schedule a screen-share to examine the code together, asking questions, making suggestions, clarifying ambiguities, and identifying potential issues.

Having a synchronous conversation like this is far more efficient than relying on asynchronous text-based feedback, which can slow down the review process and potentially introduce errors.

Pair reviewing is a crucial step in code review, and it involves two or more individuals reviewing the code together. The conversation during pair reviewing can happen through version control software or by talking to each other; being the latter a more efficient and high-bandwidth communication channel. Pair programming and pair reviewing go hand in hand, and they both have significant benefits.

For instance, when Isla and Bob review the code together by voice, they can quickly ask questions, make suggestions, explain ambiguities, and highlight potential issues. Such exchanges, if done synchronously, can save a lot of time, and individuals tend to be more respectful and gentler when communicating in person. The tone of voice and facial expressions convey additional information that would otherwise be lost in text-only communication.

However, some individuals may prefer asynchronous and text-only communication during code review. If you encounter such people, it is best to reach out to them and request a conversation. If they are still unwilling, it is better to bypass them and find someone who is interested in having a genuine conversation about the code. Building a network of relationships with individuals who can pair review code with you is an excellent way to improve the quality of code and create better code reviews for everyone involved.

Using comments to add value

When conducting a textual code review, it's important to be mindful of the comments you make and how you make them. Think of code review as a way to add value to existing code, and ensure that any comment you make does just that.

Remember that the goal of code review is to improve the code, not to tear it down. So always approach your feedback with a constructive mindset and focus on adding value.

1. Point out potential issues: If you spot a problem with the code, make sure to explain why it's an issue and offer suggestions for how to fix it. For example, instead of just saying "This won't work," try saying "This code won't work because it's missing a parameter here. I suggest adding it like this..."
2. Ask clarifying questions: If you're not sure what the code is doing, it's better to ask than to assume. Ask questions to gain a better understanding of the code, and then provide feedback based on that understanding.
3. Offer suggestions for improvement: If you see a way to make the code better, suggest it. Be specific about what you're suggesting and why you think it would improve the code. For example, "I think we could simplify this section of code by using a ternary operator instead of an if/else statement. It would make the code more concise and easier to read."
4. Provide positive feedback: If you see something you like in the code, say so! Positive feedback can be just as valuable as constructive criticism. For example, "I really like how you've structured this function. It's easy to follow and makes the code more maintainable."
5. Not my style: It's important to recognize that coding styles can vary widely among different developers, and what may seem strange or unfamiliar to you may be perfectly valid to someone else. Criticizing someone's coding style without a good reason can come across as petty and unproductive, and can even discourage them from contributing further. It's always better to focus on the actual functionality and effectiveness of the code, rather than minor stylistic differences.
6. Don’t understand what this does: It's important to remember that the code review process is intended to add value to the existing code. If you come across a piece of code that you don't understand, it's your #responsibility to try to figure it out on your own. Take the time to look up unfamiliar syntax or functions. The author of the code is likely focused on getting their work done, not on #teaching you how to perform a code review. By taking the initiative to learn and understand the code on your own, you can provide more valuable feedback during the review process.
7. Could be better: If the code is working fine but you have a suggestion to make it better, you can phrase it as a question. For instance, you can ask, "Would it be clearer to write this in a different way?" or "Do you think renaming this variable as X would make it more logical?" or "Would reusing this variable be faster, or does it not matter in this case?" By framing your suggestion as a question, you allow the author to consider it without feeling like they are being criticized.
8. Something to consider: Yes, sometimes you might have a suggestion or an idea that could be helpful, but you're not completely certain about it. Perhaps the author already considered and dismissed it or didn't think of it at all. In such cases, it's best to make your comment tentative and gentle. For example, you can say, "I was wondering if it could be beneficial to use a static function here. What are your thoughts on that?". This way, you're not coming across as critical, and you're also opening up a discussion to consider potential improvements to the code.
9. Don’t think this is right: When you come across code that you believe is incorrect or missing something, it's important to approach it with an open mind and make it a question rather than a criticism. By asking a question such as "Is this the correct way to handle this situation?" or "Shouldn't we include this piece of code to ensure proper functionality?" you can open up a discussion and get more information about the reasoning behind the code. This approach can lead to a more productive conversation and prevent any potential conflicts or misunderstandings.
10. Missed something out: The code is fine as far as it goes, but there are cases the author hasn’t considered or some important issues they’re overlooking. Use the "yes, and..." technique: "This looks great for the normal case, but I wonder what would happen if this input were really large, for example? Would it be a good idea to...?" By framing your comment as an extension of the existing code rather than a criticism, you're more likely to get a positive response and engage in productive discussion.
11. This is definitely wrong: if you believe there is an error in the code, it's best to approach them with kindness and humility. Instead of simply pointing out what's wrong, take the time to carefully phrase your response and offer suggestions. For example, you could say, 'I noticed that we continue despite logging the error. Is it safe to do so if the result is null? Perhaps it would be better to return the error here instead. What are your thoughts?

Accentuate the positive

It's important to not only focus on what's wrong with the code during a review but also to highlight what's right. Start off with positive feedback, such as complimenting the organization or function names, and follow up with respectful comments and suggestions. Even when giving constructive criticism, it's possible to find something encouraging to say at the end, like "Great job! This is really shaping up nicely."

However, if you're reviewing code from someone more senior than you, it might not be appropriate to praise them directly. Instead, show gratitude for the opportunity to review the code and express what you've learned from it.

When your vanity is wounded

Code reviews can sometimes be difficult to receive and can cause damage to one’s self-esteem. It can be discouraging to put a lot of effort into a project and then receive harsh criticism in return. When this happens, it’s natural to feel hurt and angry, but it’s important to avoid responding in a negative or defensive manner. Remember that the reviewer is likely trying to help, even if their feedback comes across as insensitive.

It’s also important to remember that not everyone is skilled at giving feedback or communicating effectively. It’s possible that the reviewer may have had a bad day or is dealing with their own personal issues. Try not to take their comments too personally and instead focus on the constructive aspects of their feedback. Even if their delivery was less than ideal, there may still be valuable insights to be gained.

In the end, it’s best to stay positive, keep an open mind, and use feedback to improve your work. Remember that everyone makes mistakes and there’s always room for improvement. By taking feedback in stride and striving to do better, you can become a better developer and produce even better work in the future.

I see what you tried to do here

It’s important to recognize condescension in code review comments and address it appropriately. While some reviewers may think they’re being helpful, it can come across as belittling and undermine the confidence of the person receiving the feedback.

If you’re the recipient of condescending comments, it’s important to take a step back and remind yourself that you’re capable and competent. Don’t let the comments make you feel small or inadequate.

If you’re the reviewer, be mindful of your tone and approach. Try to frame your feedback in a way that is respectful and encourages growth, rather than belittling the other person. Consider how you would want to be spoken to if you were in their shoes.

Ultimately, we’re all learning and growing in our roles, and it’s important to approach code reviews with a mindset of constructive feedback and support. We can all benefit from the knowledge and experience of others, but it’s important to communicate in a way that is respectful and builds up, rather than tearing down.

Stylistic nitpicks

When you receive "not my style" comments, it's best to ignore them to avoid creating unnecessary churn. Responding to these comments can lead to a cycle of random changes that serve no real purpose. If the reviewer continues to insist on the changes, you can have a private conversation with them to clarify their concerns. Ask them politely if there is something specific they can't live with or if the issue is purely a matter of style. This will help you understand their perspective and address any valid concerns they may have.

Setting the example

The ability to understand people and foster good relationships is a valuable skill in any career, including software development. Working collaboratively with a team to develop software can be challenging, but treating others with kindness, consideration, and respect is key to success.

As you progress in your career, you may find that these interpersonal skills are just as important as technical expertise. By modeling good code review practices and treating others with respect, you can set a positive example for your colleagues and contribute to a positive team culture. Keep up the good work!