The Art of Constructive Feedback: How to Write Good PR Reviews
The first real comment I received on my PR was fantastic. They praised my work and provided constructive feedback. However, the subsequent comments on other PRs were quite different. One particularly memorable comment was simply, 'Why did you do this and not that?'. As a junior developer on my first major project, I felt overwhelmed by the vast codebase and the project's specific rules.
Reflecting on this experience made me think about the etiquette of writing code reviews. It's intriguing how some people can offer helpful feedback, while others leave you feeling incompetent and out of place.
The Art of Constructive Feedback
In the dynamic world of software development, the ability to provide constructive feedback on pull requests is not just a skill - it's an art. Every pull request review is an opportunity to improve code quality, share knowledge, and strengthen collaboration in the team.
A Balancing Act
However, delivering feedback that is both useful and respectful can be a delicate balancing act. Here are some of the best practices and approaches for writing reviews that are insightful, encouraging, and lead to big improvements in the team to consider:
1. Start with a Positive Note: Begin your review by acknowledging what has been done well. This sets a positive tone and shows appreciation for the contributor's efforts.
2. Be Specific and Clear: Point out specific issues or areas for improvement. Instead of vague comments like "This needs work," provide clear, actionable feedback. For example, "The function calculateInterest could be optimized for better performance by..."
3. Explain Why: When suggesting changes, explain why the change is necessary or beneficial. This helps the author understand the reasoning behind your feedback and learn from it, especially if he is new to the project.
4. Use Questions Rather Than Statements: Framing feedback as questions can be less confrontational. For example, "Have you considered implementing a caching mechanism here for efficiency?" instead of "You should use caching here."
5. Offer Solutions or Alternatives: Where possible, offer solutions or alternatives to the issues you raise. This can help guide the contributor towards the desired outcome, especially if he is a junior developer.
6. Be Respectful and Professional: Always maintain a respectful and professional tone. Avoid personal comments and focus solely on the code. It's about improving the project, not making anyone feel bad.
7. Be Open to Discussion: Be open to a healthy discussion. Sometimes, your feedback might initiate a valuable exchange of ideas.
8. Balance Between Nitpicking and Necessary Feedback: It's important to balance between being overly critical about minor issues and providing necessary constructive feedback. I even suggest if it’s something minor to contact the developer in Teams or Slack, rather than publicly saying he made some typo or small issue that can be fixed in 2 minutes.
9. Lead by Example: Demonstrate good practices in your own code submissions. This sets a standard for others to follow.
10. Prioritize Feedback: Not all feedback is equally important. Distinguish between 'must-haves' and 'nice-to-haves'.
By using these tips, you'll give helpful, friendly, and effective feedback. This not only makes the code better but also helps create a team environment that's collaborative and respectful.