Developers: Three ways to make your pull requests easier to review
To be effective in their role, developers need to learn how to work productively with their peers and the lead developer.
An important piece of this is learning the ropes on how to make pull requests that are easy to review.
What follows are three ways to make them better for the benefit of the people that review them. If you follow these tips, you’ll collaborate more effectively and demonstrate more competence and value.
1 — Add comments that answer “What does it do?” as a quick reference for the people who will review your code.
This is where having empathy can come in handy. Before you commit the code you’ve just written, ask yourself: “Would it be easy for me to understand what this code does if I had never seen it before?”
If you can answer yes to that question then, depending on conventions at your shop, it’s probably ok to commit code without comments.
However, if you cannot 100% answer yes, then it might be wise and a benefit to your relationship with your lead dev or peers to add a brief inline comment explaining what your code does.
Think of it as a quick reference that makes your reviewers’ lives easier.
2 — Answer “Why?” in your pull request descriptions to provide a sneak preview of what your code is about.
As I just covered, the comments in your code are where you answer “What?”.
Your pull request description is where you can answer “Why?”. In your pull requests, it’s a good idea to address why you solved the problem in the way you did so the dev reviewing your code can get a sense of your approach.
This is like providing them with a shortcut to understanding why you wrote it that way prior to even looking at your code. Think of it as the trailer or teaser before a movie or a show. These give you a sense of what you’re getting beforehand and provide context.
3 — Squash multiple commits on the same pull request.
The purpose of squashing commits is to ensure pull requests with multiple commits end up with just one all-encompassing commit when merged.
This makes it easier for the developer who reviews your pull requests to understand what the pull request is about without having to look through multiple commits.
This also alludes to the importance of making your pull requests as small and as focused as possible. You want to make it simple for your lead dev or peers to understand what the pull request pertains to.
Depending on the tools you use, there are multiple ways to squash commits. You can use the command line or your IDE. Here’s an article that explains how to squash commits using the command line.
Making things as easy as possible on the developers who review your code is a great way to cultivate an atmosphere of productivity, collaboration, and harmony within your team.
Leverage these three ways to make your pull requests easier to review, and you’ll achieve this and win many friends.