Doing code reviews isn’t easy. Doing them well is even harder. It’s not just about the technical stuff—it’s also about being friendly. In this post, I’ll talk about some ways to make your code reviews better for everyone.
Explain Your Suggestions
Sometimes it’s good to explain why you’re suggesting a change. This helps the developer understand what you mean and learn something new. You can link to your company’s style guide or other helpful resources. 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. Make sure that the developer really understands how your suggestion improves code health.
Instead of saying something is “bad,” explain why it needs to be fixed. For example, say “I found this code hard to understand, maybe we should split it up?“. 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 Advice
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. When you comment on code, don’t criticize the author. Focus on the code and how it can be improved. If something’s unclear, ask for clarification instead of assuming they don’t know what they’re doing. Avoid using “you” in your comments, as it can feel like a personal attack. 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.
Point Out the Good Stuff
Don’t just focus on mistakes. 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.
If you see something good, say so! It’ll make the team feel good and motivate them to keep doing great work.
We All Make Mistakes
Remember, everyone messes up sometimes. Whether you’re a beginner or an expert, it’s okay to make mistakes. It may be caused by a bad day, bad mood, lack of domain knowledge, or overload with duties. Be kind and understanding.
I hope these tips make your code reviews more enjoyable for everyone. Good reviews help the whole team get better and grow together.
