I love reviewing pull requests. I think this might be the single most valuable thing you can do on a project. Any book you could buy off the shelf of your local bookstore has gone through a rigorous editing process before it saw print. If you’re writing code and publishing it for others to use, there’s no excuse to treat it with any less care than a best-selling novel.
One of my favorite tips for making PR reviews more useful, efficient, and enjoyable is Github’s “Saved replies.” If you’re not using these yet on your project, you will be by the end of this post.
How Saved Replies work
Buried deep in the bowels of your Github account is a small feature called “Saved replies.” The name is pretty self-explanatory. You can create and save templates that you can then insert anywhere in Github where there’s a markdown text box (new Pull Requests, Issues, PR review comments, etc.).
To edit your Saved replies, first go to your account settings. You’ll see “Saved replies” near the bottom of the left-hand menu. Once there, you’ll have a markdown editor where you can save reply content, and give each reply a custom title.
Creating Your PR Review Prompts
Your team should agree on a set of PR comment types that you will all use, and you should share an understanding of meaning/intent. I maintain a gist of the comment types I like to use. This was pulled from a blog post that’s now seven years old 😅. Your team should create a similar document that everyone can always easily reference. The exact set you use is up to you and your team, but I’d recommend a minimum of:
- Comments to note an issue that absolutely needs to get fixed — this requires action from the code author.
- Something to note an issue that the team could fix, but it’s not necessary (or maybe it’s up for debate) — this may require action from the code author.
- Comments to note confusion/a request for clarity — this requires action from the code author in the form of a reply and may lead to further notes.
- Something to note a comment that doesn’t require action from the code author.
As you can see from my screenshot above, I format all my Saved replies with a keyword indicating the type of comment and a link to the gist that contains further information about the types. Everyone on the team should create the same set of Saved replies in their respective Github accounts.
Using Your Saved Replies on PR Reviews
Now that your team has a shared set of comment types, it’s time to get reviewin’! As you go through file changes in a pull request, when you click on a line of code to leave a comment, you can select from your set of Saved replies. As you can see, there’s even a handy keyboard shortcut (ctrl+<num>). Once you select a saved reply, you can then add your specific comments below the template text.
I’ve found that having this saved set of reply templates helps me better focus and frame the feedback I leave on PRs. I’m forced to ask myself what kind of comment I’m making each time. The reply type heading also makes it easier for me to summarize what I want. I don’t have to worry about explaining the outcome I’d like from each comment because I know my teammates understand the context of each comment type.
It also makes it much easier for the code author to follow up after a review. That’s because I don’t need to parse through every comment linearly. I can start with the required changes, and then move on to clarifying questions. Then, if there’s time, I can read through the non-actionable comments.
Reviewing the Reviewers
Learning to receive feedback is an important skill, but learning to give feedback well is equally important. I’ve observed programming teams ignore code quality and struggle with dysfunction around code reviews. This happens because there isn’t a shared and agreed-upon standard for how to conduct them and what expectations each individual has. It can be difficult to receive critical feedback about code that you’ve struggled with for hours (days? weeks?). When faced with fuzzy feedback and emotionally-charged reactions to code reviews, it’s no wonder so many teams choose to not bother with code reviews at all.
Saved Replies for a More Pleasant PR Review
You wouldn’t want to read a book with a ton of typos, bad formatting, and confusing sentences. So, you shouldn’t ship code like that either (apologies to e.e. cummings). Make your PR reviews something you look forward to! A shared set of Saved replies is a great way to create a more pleasant experience for both the reviewer and the reviewee.
Comments are closed.