Doing code reviews is not an easy task. Doing a good code review is even more difficult and responsible job. It is not only a technical process but also a social one. In this article, I discuss a few techniques that may improve your code reviews and make them more human friendly to keep positive relationships with your colleagues.
Explain
You don't always need to do it, but sometimes it's appropriate to give a bit more explanation about your suggestions. It's a good practice to explain both your suggested change and the reason for the change. This helps the developer understand why you are making your comment and there is a chance that the author of the pull request may learn something new.
If you can, provide a link to a section in your company's style guide, to language or library documentation, or to the best practice you’re following. Make sure that the developer really understands how your suggestion improves code health.
Code can sometimes be just messy or written in an unintuitive way. Instead of formulating judgments like "This is bad" or "This line of code is unnecessary", try to explain why this code should be refactored. You could write your comment in a nicer way, for instance, "I found this code hard to understand, what about splitting this complex function?". Referring to the issue in this way helps the developer understand why you are making your comment.
By the way, try to encourage developers to simplify code or add code comments instead of just explaining the complexity to you, so those changes can be helpful also to future code readers.
Give guidance
It's not easy to find a good balance between pointing out problems and providing direct guidance. Code review is an opportunity for developers to learn and protect themselves from mistakes. But giving a ready solution to a problem is just taking away that opportunity.
Instead, let developers explore, research, and make a decision. This helps them to learn. On the other hand, if you leave comments like this one "Can we simplify this complex function?", you're not actually helping much. So instead of only pointing out problems, you should also share some suggestions, instructions, or maybe even a code example.
Remember that a hidden goal of code reviews is also to improve developers' skills so they require less and less guidance over time.
Do not judge
Code review comments should be written in a neutral language. You should never critique the author, instead focus on the code and possible improvements.
If you find something difficult to understand, ask for clarification rather than assuming ignorance or making judgments in comments, like "this can never work". If you want to critique the code of a colleague, make sure to do so in a respectful way and always include some possible ways for improvement.
To make sure you're not critiquing the author, avoid using the word "you" in your message. When the author sees "you" in a comment, they may take the criticism personally. Consider this sentence:
- "You made this code hard to understand."
A comment like this brings the focus away from the code, and the author can interpret it as a personal attack.
Writing comments without the word "you" shouldn't be hard, you have at least two options.
Replace "you" with "we"
"This function you wrote is hard to read. Can you simplify it?"
"I find this function difficult to understand. Can we simplify it?"
Which comment would you prefer to receive as an author?
I bet that you would prefer the second one. That's because the second example brings focus to the code and the comment is not judging anybody.
Replace commands with requests
Another option is to omit the subject from the sentence. Look at these two examples:
"You should split this function into smaller ones."
"What about splitting this function so the code is easier to read and debug in the future?"
The second example is not only formulated in a friendly way but it also brings reasoning to your comment.
Point out good work
Don't limit your code review to only finding errors. Pointing out also good work definitely improves the team spirit and is a good motivator. Don't forget to do it especially if you have learned something from this code or if you noticed a solution you wouldn’t have come up with yourself.
Everyone makes mistakes
Remember that we're all humans and it doesn't matter if it's a beginner or experienced developer's code, the truth is that everyone makes mistakes. It may be caused by a bad day, bad mood, lack of domain knowledge, or overload with duties.
I hope that my tips will encourage you to strive for a stress-free and developer-friendly code review. Let's remember that good code reviews not only improve the merged code but they bring benefits to all team members. We can also inspire others and contribute to their self-development.
This article was originally published on my personal site mateuszjanusz.dev.
Top comments (2)
Really good point!
Good tips.