Inclusive and Productive Collaboration in Code Reviews
Code reviews can often be a source of stress and frustration and they should not be. From my original article that defined code review and their benefits:
#1 rule: This is about sharing knowledge and improving, not to catch someone out or shame them.
Code reviews are one of the key spaces where you can foster an inclusive and collaborative culture in Software development. In general, code reviews should always be about the code and not the developer, so avoid using using you, your, etc. A key to a successful code review is to keep it short and effective. A way to achieve this goal is to make your comments clear and actionable:
- Be kind: Compliment the person who wrote the code when it teaches you something. This will help create a relationship and may break barriers for the next time. Also, remember the context and background of the person asking for the review. Is the developer a new grad and this is the first time they have ever experienced a peer review? Is there a power dynamic between the 2 of you (i.e. are you much more experienced an/or influential in the company)?
- Explain your reasoning: when recommending a change and suggesting another approach, explain why, so the author can understand the motivation. Instead of “add @override” explain “here it seems we need to add @override otherwise the method is simply overloading. See this reference on overload/override”
- Provide suggestions: avoid simply stating “this method is too long” but take a few minutes and write an idea to help the person get started “This methods seems to be over the limit of our standard, maybe we can extract this logic into a submethod”
- If you cannot understand the code, ask specific questions. Encourage developers to simplify code or add code comments instead of just explaining the complexity to you. Instead of “this is very confusing, please clarify”, explain “I do not understand what are the parameters of the method and why we need this processing on it. Can you add more comments to provide context?”
- Specify the importance of your comment: for example prefix “nit:” (short for nitpick) for small style recommendations
Finally, if there are too many comments or back and forth on a review, stop and meet in person or Video Call to discuss the issue. This may be a case where there is a need to go back to design by creating or enhancing a design document summarizing the approach taken in the code review.
It is worth stating again:
Compliment the person who wrote the code when it teaches you something.
Code reviews are not just about finding mistakes, but also about learning. Also, the sooner you find a potential issue the less impact it will have, so don’t neglect using a critical eye. We all have a different journey and as a result have a different perspective, which is invaluable to the review process. If you show a piece of code to 10 developers, they will have 10 different things say.
Some addition reading on Diversity and Inclusion:
This article is a series on how to be an effective code reviewer. Please see my previous article that provides background on Code Reviews and Their Benefits. Other articles in the series are:
4 Rules of Thumb for Providing Effective Code Review Feedback
How to Provide Effective Feedback based on Code Review Type
Imposter Syndrome: How to overcome it during Code Reviews
Thank you to Alice Bonhomme-Biais, co-author of this article. We originally presented the content at Grace Hopper 2020 as a part of a presentation on “Finding your Voice as a Code Reviewer”
