The pull request is critical to development teams. They provide a mechanism to check in about a piece of code and where it fits within the greater context. They are crucial checkpoints to provide feedback.
Whether you are planning to contribute to an Open Source project. Entering the development workforce for the first time. Or you are a seasoned programmer wanting to improve the process. Making the most out of pull requests will change your development process forever.
No One Person Owns The Code
For pull requests to be effective everyone within the team has to check their ego at the door. It is very easy for developers to become invested in their code. This is OK if they are open to feedback.
The pull request is an opportunity for others within the team to provide feedback. Why do they need to provide feedback?
- To verify the code meets the standards that the team has defined.
- To confirm the changes meet the technical requirements.
- To understand the changes for future maintenance. *To make sure the implementation is supportable and maintainable.
These are three quick reasons that are hard to disagree with. A pull request is an opportunity for the team to provide feedback. The team owns and maintains the code, not a single developer. If this condition is not met it destroys team cultures and the pull request process.
How To Be A Good Reviewee
You have checked your ego and want feedback from your team. You have busted your ass developing a feature and are ready to open a pull request. It is critical that you do your part as the reviewee to get the most out of the pull request process.
- Verify all tests associated with the code pass before opening a PR.
- Remove any unnecessary code or comments before opening a PR.
- Try to keep your PR small as smaller chunks of code are easier to review than massive changesets.
- Provide the reviewer as much context as possible. Use the PR description to explain what you did, why you did it, and why you believe it to be the right solution. Call out any assumptions you made and anything you were unsure about.
These guidelines improve the pull request process. They optimize for effective, concise, and clear feedback opportunities for the reviewer. The last bullet point is by far the most important. The reviewer is going to be coming into your pull request cold. They will have a mental context switch. Be cognizant of this and provide as much context as you can about your code.
How To Be A Good Reviewer
Equally as important as being a good reviewee is being a good reviewer. This is an important role to be in for any given development team. The reviewer is making sure the code of another developer meets team agreements. These agreements could be team agreements, technical requirements, or feature requests.
It is important to recognize that an individual is looking to the reviewer for feedback. If you find yourself being a reviewer on a pull request, here are some things to keep in mind.
- Don’t be an asshole.
- Always verify all tests pass.
- Never blindly approve a pull request. Verify the changes and give it your full attention.
- Understand the context the code was written in.
- Ask questions if something is not clear.
A good pull request should give the reviewer confidence. If it doesn’t that is OK because this is the time to catch these things. If as a reviewer you are not confident in the PR then provide constructive feedback.
- Explain what is missing and how to make it better.
- Help the developer understand why these things are necessary.
- Remember don’t be an asshole and instead be helpful.
If they are a new developer then you may need to do more than explain the issues. It may be the case that you need to help them out with an example. Take the time to help the developer understand why this pull request is not ready. Often times reviewers don’t do this. It wastes time, frustrates developers, and introduces friction in the PR process.
Help others out.
Conclusion
A pull request represents a checkpoint for feedback. The pull request process will be different depending on the project you are working on. But the feedback process will always be present in some form or another.
There will always be a developer needing feedback from someone else. These guidelines are talking about pull requests, but they apply to general feedback. As someone that needs feedback explain where you are, how you got there, and things you are assuming or not sure about. Then as someone that is providing feedback, don’t be an asshole, give the problem your full attention, and help the other person.