Skip to Content
LearnCode ReviewCommunicationPR Descriptions

PR Descriptions

Let’s look at how to suggest improvements for PR descriptions in code reviews. We’ll show you a simple example and explain why the feedback matters.

The Scenario

A developer has submitted a PR with a minimal description. The code works but could use a better description.

PR_DESCRIPTION.md
# Description
 
Added user validation

PR Comment

Choose the comment that you think is the most constructive and helpful.

# Description
 
Added user validation to improve data quality and prevent
invalid user data from entering the system.
 
## Changes
 
- Added input validation for user fields (name, email, age)
- Added error messages for invalid inputs
- Added unit tests for validation logic
 
## Testing
 
- Added test cases for valid and invalid inputs
- Verified error messages are clear and helpful
- Tested with various edge cases
 
## Impact
 
- Prevents invalid data from being saved
- Improves user experience with clear error messages
- Makes the system more robust

Click here to learn more

Improvements

1. Clarity

  • Clear explanation of changes
  • Better context for reviewers
  • Easier to understand the purpose

2. Documentation

  • Better project history
  • Clearer change tracking
  • Improved knowledge sharing

3. Review Process

  • More efficient reviews
  • Better feedback quality
  • Faster review completion

Tips

1. Start Positive

  • Acknowledge the working code
  • Show you understand the current approach
  • Example: “Great work on the user validation!“

2. Explain the Benefits

  • Why do better descriptions matter?
  • How do they help?
  • Example: “This makes the review process more efficient”

3. Be Specific

  • Suggest concrete improvements
  • Explain why they matter
  • Example: “Adding a detailed description helps reviewers understand the changes”

4. Keep It Friendly

  • Focus on improvement, not criticism
  • Use encouraging language
  • Example: “Thanks for considering documentation!”

Common Pitfalls to Avoid

1. Being Too Critical

  • ❌ “This description is terrible.”
  • ✅ “Good work! Here’s how we can make it even more helpful.”

2. Not Explaining Why

  • ❌ “Add more details.”
  • ✅ “Adding more details helps reviewers understand the changes.”

3. Ignoring the Positive

  • ❌ “This needs a better description.”
  • ✅ “Great work! Here’s how we can make it even more informative.”

Remember: The goal is to help your teammate write better code while maintaining a positive and collaborative environment!

Last updated on
Positive ReinforcementReview Speed