Good code review etiquette

Sara Verdi
Sara Verdi
Graphite software engineer

Adopting good code review etiquette is part of creating a respectful and constructive work environment. This guide will cover the best practices, dos and don'ts, and effective communication strategies to enhance your code review experience.

Good code review etiquette encompasses behaviors and practices that make sure reviews are productive, respectful, and beneficial for all parties involved. It's all about maintaining professionalism and fostering a collaborative atmosphere while providing constructive feedback. Here are some key aspects of code review etiquette:

  1. Be specific in your feedback: Instead of saying, “This isn’t right,” provide specific reasons for your suggestions. For example, “I think this function can be simplified by using a map instead of a loop.”

  2. Use positive language: Frame your feedback positively to encourage the developer. For instance, instead of stating, “This code is messy,” say, “This code can be more readable with some refactoring.”

  3. Limit the scope of reviews: Keep your reviews focused. A review that’s too broad can overwhelm the author. Aim for a manageable number of changes, ideally around 200-400 lines of code.

  4. Provide context: When suggesting changes, explain the rationale behind your suggestions. For example, “Refactoring this function will enhance its testability and maintainability.”

  1. Acknowledge good work: Always highlight what the author has done well. For instance, “Great job on the implementation of this feature! The tests are thorough and well-written.”

  2. Be respectful: Treat the author’s work with respect. Avoid making personal remarks. Use phrases like, “I suggest considering this approach,” rather than, “You should have done it this way.”

  3. Encourage collaboration: Invite discussions around your feedback. You might say, “What do you think about this approach?”

  4. Be mindful of tone: Maintain a polite and professional tone in your comments. Avoid sarcasm or harsh language, which can be misinterpreted and create tension.

  1. Be constructive: Use phrases like, “Consider changing this part to improve performance,” instead of “This is wrong.” This not only communicates your thoughts clearly but also helps the author learn.

  2. Ask questions: Questions can guide authors to reflect on their decisions. For example, “What was your reasoning for choosing this method over another?”

  3. Summarize your thoughts: If your review is lengthy, start with a summary of the main points you want to address. This helps the author understand the key issues upfront.

  • Focus on the code: Center your comments on the code and its logic, not the developer’s skills or capabilities.
  • Follow up: After providing feedback, check in with the author to see if they have questions or need clarification.
  • Use tools: Leverage tools like Graphite Reviewer to obtain instant feedback on pull requests and significantly cut down on review cycles to reduce your team's overall time-to-merge
  • Don’t make it personal: Avoid comments that could be perceived as personal attacks. Focus on the code, not the person.
  • Don’t overload with comments: Too many comments can be overwhelming. Prioritize your feedback and keep it manageable.
  • Don’t ignore the process: Follow your team’s established guidelines for code reviews to ensure consistency.
  1. Set clear expectations: Ensure everyone knows the goals of the code review process. For example, aim for knowledge sharing, improving code quality, and fostering collaboration.

  2. Create a culture of learning: Encourage team members to view code reviews as learning opportunities. Use phrases like, “I learned something new from your implementation, and I think we can further enhance it by...”

  3. Be open to feedback: As a reviewer, be receptive to feedback on your comments. This can help improve your reviewing skills over time.

By adhering to the principles of respect, constructive feedback, and effective communication, you can create a collaborative atmosphere that enhances the quality of code and the skills of your team members. Plus, utilizing tools like Graphite can ensure that your code reviews are efficient and beneficial for all involved.

Git inspired
Graphite's CLI and VS Code extension make working with Git effortless.
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2