Code Reviews: Writing Good PRs
This week we are talking about how to write a good pull request!
This week I spent some time with Dusti Arab from The Reinvention Co. She was absolutely incredible to work with and I learned a ton from her.
We put together a strategy for my newsletter and some other things I have going on, like the Overcommitted podcast. Expect some changes to come based on the things that I learned from her!
Next week I will be in Berlin talking at Gophercon EU, and hanging out with my super cool brother that lives in Berlin. If you have any recommendations for the area, please let me know!
Highlights
Things I've been doing on the internet
- Podcast: Overcommitted Ep. 10 | Collaborating with product with Hirsch Singhal
- This was our first podcast with a guest and it was a ton of fun! If you are interested in being on the podcast, let me know! We would love to have you.
- Illustration:
Things I've enjoyed on the internet this week
If you've got something you want me to read and feature in this newsletter, send it to me at brittany@balancedengineer.com!
- Illustration: Your ears are plugged - The Oatmeal
- It has been a while since I checked out The Oatmeal but I always enjoy it.
- Website: Rural Glass Design
- I made this site for a friend and finally got it finished this week! I love her work. If you're into creative stained glass, you should check it out!
Onto the content!
This month we're talking about code reviews.
June Theme: Code Reviews
The best code reviews start before anyone else looks at your code. How you structure and present your pull request can make the difference between a productive discussion and a frustrating back-and-forth that drags on for days.
After reviewing hundreds of pull requests and having my own reviewed by others, I've learned that the quality of the review is often determined by how well the author sets it up. Today, let's explore how to write pull requests that make reviewers excited to dive in rather than dreading the task.
Write a Description That Tells the Story
Your pull request description is your chance to guide reviewers through your thinking. It shouldn't just state what changed—it should explain why it changed and how you approached the problem.
A good PR description answers these questions:
- What problem does this solve? Give context that helps reviewers understand the business or technical need
- How did you solve it? Explain your approach and any trade-offs you considered
- What should reviewers focus on? Highlight areas where you want specific feedback
For example, instead of:
"Fixed the user login bug"
Try:
"Fixed authentication issue where users with special characters in passwords couldn't log in. The problem was in our URL encoding logic—we were double-encoding passwords before sending them to the auth service. This change updates the encoding to happen only once and adds tests for edge cases with special characters."
Here's where AI tools like GitHub Copilot can be incredibly helpful. Instead of staring at a blank description box, you can use Copilot to generate a starting point based on your code changes, then refine it to include the context that reviewers need.
Pre-Review Your Own Code
Before hitting "Create Pull Request," take a few minutes to review your own changes. This serves two purposes: you'll catch obvious issues before others see them, and you'll identify areas that might confuse reviewers.
When you spot something that might raise questions, add a supporting comment explaining your reasoning. These comments are invaluable for reviewers and show that you've thought critically about your decisions.
Some situations where explanatory comments are particularly helpful:
- Complex logic or algorithms: Explain the approach you took and why
- Unusual patterns or workarounds: Describe what you tried first and why this solution was necessary
- Performance considerations: Note any trade-offs between readability and performance
- External dependencies: Explain choices around libraries, APIs, or third-party services
For instance, if you chose a less obvious approach for performance reasons, a comment like "Using a dictionary here instead of an array for search because we're expecting up to 10k items" saves reviewers from wondering why you didn't use the simpler approach.
Make It Easy to Test and Verify
The third key to great pull requests is making it simple for reviewers to understand and verify your changes. This means including clear testing instructions and ensuring your changes are focused.
Include testing steps in your description. Even if you have automated tests, provide manual testing steps that reviewers can follow. This helps them understand the user experience and builds confidence in your changes.
Keep your pull requests focused. Large PRs with multiple unrelated changes are hard to review effectively. If you find yourself fixing several different issues or adding multiple features, consider breaking them into separate pull requests. Your reviewers (and your future self) will thank you.
Update related documentation. If your changes affect how something works, update relevant documentation, README files, or code comments in the same PR. This prevents the common problem of code and documentation getting out of sync.
The Impact of Better Pull Requests
When you invest time in writing clear, well-structured pull requests, several things happen:
- Reviews happen faster because reviewers can quickly understand the context and focus on meaningful feedback rather than trying to decipher your intentions.
- The quality of feedback improves because reviewers can engage with your actual decisions rather than getting stuck on confusion about what you're trying to accomplish.
- Knowledge sharing increases because your explanations help teammates learn from your problem-solving approach and the trade-offs you considered (plus I can't tell you how many times I have re-read old PRs to get context on how something was introduced).
Most importantly, you'll find that the act of explaining your code often helps you spot improvements before anyone else even looks at it, making for a shorter review cycle as you fix the low hanging fruit before your teammates provide their own review.
Have comments or questions about this newsletter? Or just want to be internet friends? Send me an email at brittany@balancedengineer.com or reach out on Bluesky or LinkedIn.
Thank you for subscribing. It would be incredibly helpful if you tell your friends about this newsletter if you like it! :)