How to write good code review comments

Quality feedback not only enhances the codebase but also helps teams better understand how to work with one another--and writing effective code review comments is a cornerstone of this process. In this guide, we'll take a look at various types of comments, provide examples, and offer suggestions on how to improve your code review feedback.

Understanding code review comment types

Before we get into the examples, it’s important to categorize the types of code review comments you might encounter or use:

1. Blocking comments: These comments indicate critical issues that need to be addressed before the code can be merged. For instance, if a function has a security vulnerability, a blocking comment might read:

   • "This function is vulnerable to SQL injection. Please use parameterized queries to fix this issue."

2. Nits: Nits (short for nitpicks) are minor issues that don’t significantly affect the code’s functionality but could improve code quality or style. A nit might be phrased as:

   • "Consider renaming this variable to be more descriptive."

Common types of code review comments

Understanding the different types of comments can help in structuring your feedback effectively. Here are some common comment types:

• Code quality comments: Suggestions focused on improving readability, maintainability, or performance.

  • "This loop could be simplified using the map function."

• Functionality comments: These point out bugs or issues in how the code performs.

  • "This method does not handle null values correctly."

• Documentation comments: Recommendations for improving or adding documentation.

  • "Please add docstrings to this function to clarify its purpose and parameters."

Examples of good code review comments

Providing clear and constructive feedback is essential for effective code reviews. Here are some examples of good code review comments:

• Specific and actionable:

  • "The calculateTotal function lacks error handling for invalid input. Please add checks for negative numbers."

• Positive reinforcement:

  • "Great job on implementing the caching! It significantly improves performance."

• Encouraging collaboration:

  • "I noticed you used a different approach for sorting. Can we discuss why you chose this method over the built-in sort function?"

Examples of poor code review comments

It’s just as important to recognize what constitutes a bad code review comment. Poor feedback can lead to confusion or resentment among team members. Here are some examples:

• Vague comments:

  • "This code is bad." Such comments provide no actionable insight and can demoralize the developer.

• Personal attacks:

  • "I can’t believe you wrote this. You should know better." This approach is unprofessional and can create a hostile environment.

Language and tone in code reviews

The language you use in your comments is important. Here are some guidelines:

• Be respectful and professional: Always use a polite tone.

  • Instead of saying, "You messed this up," say, "I noticed an issue with this implementation."

• Focus on the code, not the person: Keep the feedback centered on the code.

  • Use phrases like "This approach may not be optimal," rather than "You did this wrong."

• Explain yourself: Help the developer understand the reasoning behind your comment.

  • While it’s not always necessary to include this level of detail in your review comments, there are times when it’s helpful to provide additional context:
  • Rather than saying, "Consider renaming this variable to something more descriptive," try "Consider renaming this variable to something more descriptive to improve readability and align with our best practices for maintainability."

How to write good code review comments

To ensure your comments are effective, consider the following tips:

1. Be concise but thorough: Aim for clarity without overwhelming detail.

   • "This logic can be simplified using a guard clause, which enhances readability."

2. Use examples: Whenever possible, refer to specific lines of code or provide examples to clarify your points.

   • "In line 45, consider using a switch statement instead of multiple if conditions for better readability."

3. Encourage discussion: Foster a collaborative environment by inviting discussion.

   • "What do you think about using a different approach here? Let’s brainstorm together."

4. Suggest improvements:

• "To improve performance, consider using asynchronous calls here."

5. Highlight best practices:

• "Using constants for magic numbers enhances maintainability. Let’s define those at the top."

6. Request clarification:

• "Could you explain the reasoning behind this approach? It might help us understand better."

Utilizing Graphite for effective code reviews

Graphite makes it easy to review pull requests and leave actionable, thoughtful feedback. You’ll be notified when a PR needs your attention through either the "Needs Review" section or via Slack integration.

Start a review

Hover over a line number in Graphite to leave a comment on single or multiple lines, including changed or unchanged code. Use markdown formatting to clearly express your thoughts, and toggle between markdown and preview mode using the "eye" icon.

Post comments

For straightforward feedback, select Post thread to submit immediately. For more detailed reviews, use Add to review to batch your comments and submit them later with your final review.

Leave good comments

When leaving feedback, consider all of what we've covered above. Explain your reasoning, reference best practices, or suggest improvements to code quality to make sure your comments are constructive and guide the developer toward better solutions.

Suggested edits

You can also directly suggest code changes, allowing the author to accept your changes with the click of a button.

Final review

After completing your review, hover over the review bar and choose to Request changes, Add comments, or Approve. All pending comments will be posted with your final review, helping maintain clarity and organization.

Takeaways

By applying the principles and using the examples provided in this guide, you can significantly improve the quality of your code review comments and ensure they are constructive, respectful, and beneficial for your team.