Inclusive and Productive Collaboration in Code Reviews

Photo by fauxels from Pexels

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