Writing a code of conduct for code review feedback

Creating a code of conduct for code reviews helps foster a respectful and constructive environment during the code review process. Code reviews are about collaboration and learning, not criticism. This guide outlines best practices for code review feedback, emphasizes code review etiquette rules, and highlights Graphite's PR inbox as a tool for organizing and improving feedback workflows.

Why a code of conduct for code reviews matters

Code reviews can feel personal, as they involve direct feedback on an individual’s work. A code of conduct for code reviews matters because it helps keep feedback focused on improving the code, not tearing down the person who wrote it, making the whole process more productive and less stressful. A well-defined code of conduct ensures:

• Constructive communication.
• Respectful interactions.
• Consistency in feedback.
• Improved code quality without hurting morale.

Key principles of a code of conduct for code reviews

1. Focus on the code, not the person behind the code

• Do: “This method could use better naming for clarity.”
• Don’t: “You always name things poorly.”
• Keep feedback objective and avoid personal attributions.

2. Be specific and actionable

• Provide clear and actionable suggestions.
• Do: “Consider using a Set instead of a List here to prevent duplicates.”
• Don’t: “This approach is bad.”

3. Maintain a positive tone

• Use language that conveys improvement opportunities without sounding harsh.
• Do: “Great job on the structure! One small suggestion—adding comments here could improve maintainability.”
• Don’t: “This structure is fine, but the comments are missing again.”

4. Respect team standards

• Ensure feedback aligns with established team coding standards and guidelines.
• Tip: Use linting tools to enforce coding standards at the review level.

5. Limit nitpicking

• Avoid overwhelming contributors with minor style preferences unless style is explicitly the goal of the review.
• Use automated tools to catch stylistic issues before code reaches review.

6. Acknowledge good work

• Highlight what was done well to balance critique with encouragement.
• Do: “The implementation of the caching mechanism is excellent. This change will significantly improve performance!”

Guidelines for writing feedback

1. Start with the big picture

   • Discuss architecture and logic issues first before diving into line-by-line comments.
   • Example: “This approach works, but it might be better to separate concerns by introducing a helper function.”

2. Keep comments concise

   • Avoid overloading contributors with lengthy explanations unless it's totally necessary.

3. Ask questions instead of dictating

   • Do: “Have you considered using a binary search algorithm here?”
   • Don’t: “Rewrite this to use binary search.”

4. Use inline comments wisely

   • Inline comments should be specific to the line of code they refer to, while broader discussions can be added to the PR thread.

Best practices for code review feedback with Graphite’s PR Inbox

Graphite’s PR inbox simplifies and organizes the code review process, making it easier to uphold feedback etiquette:

• Sections for prioritized feedback: The inbox categorizes PRs (e.g., “Needs Your Review,” “Waiting for Review”) to ensure timely and focused feedback.
• Customizable filters: Tailor filters to focus on PRs that need attention, ensuring no review is delayed.
• Collaboration-friendly: Share section configurations with teammates to maintain consistent feedback workflows across the team.
• Search and track: Use fuzzy search to find PRs and track feedback history, ensuring consistency and reducing redundancy in feedback.

For example, if a PR falls into the “Needs Your Review” section, the reviewer knows that it’s waiting for action. This structured workflow helps ensure prompt and constructive feedback that adheres to the team’s code of conduct.

Example of some code review etiquette rules your teams can adopt

1. Respect all contributors: Feedback should be constructive and professional.
2. Keep discussions public: Use PR threads for discussions unless the topic is sensitive.
3. Avoid blocking for minor issues: Reserve blocking comments for critical functionality or security issues.
4. Provide context: Explain the reasoning behind your suggestions to facilitate learning.

Summary

Establishing a clear code of conduct for code reviews ensures feedback is actionable, respectful, and aligned with team standards. Leveraging tools like Graphite's PR inbox can further enable teams to focus on delivering high-quality software while maintaining a positive and collaborative atmosphere. By following these guidelines, you can foster a culture of continuous improvement and mutual respect, and empower your developers to build and ship higher-quality software.