Trying to provide helpful pull request reviews
How I unblocked a frozen pull request
A few weeks ago, I saw a pull request to modify one of our web jobs which codebase is pretty old and had no tests. The pull request had no tests either. The thing is that we decided to make unit testing mandatory for any pull requests a couple
I started reviewing the code when I noticed someone else already posted a review. A pretty laconic “please add tests”. Not a bad nor a mean review but not a really helpful one. Proof of it is that it was posted about an hour before and the pull request was blocked. Indeed we do not untested logic to enter or remain in our software. Yes, it is aligned with our new policy about tests. That being said, the
This is where I stepped in, I reviewed the code and found a way to make it testable. I then suggested a few minor changes in the existing codebase to make it testable. Within thirty minutes he modified the code and was pretty happy to have tests for the logic he improved. Eventually, I went on and approved his pull request then the first reviewer followed up.
What went wrong with the first review
Please add tests
In most cases “please add tests” is enough to do the trick. The code is designed properly and decoupling is applied wherever possible. “Please add tests” is enough if the tests were not written because of laziness or just got forgotten. However, in this particular case, the reviewer did not take in consideration the context of the change. Indeed, it was an update to an old project designed at a time where the backend team was a couple of guys trying to launch a company. Delivering the software was prioritised over making it easily maintainable. In order to allow a business to take off, testing and decoupling was left for another day. Taking these factors in consideration I have been able to come up with a few strategic changes that eventually allowed to add some tests.
You may have noticed the two different approaches and their effect here. On one hand, turning a change of context into a problem, on the other hand, suggesting a solution. The first one had the pull request frozen for an hour where the latter allowed the pull request to move forward and the code to be merged. As software engineers we need to help others moving forward and propose solutions not problems. Solving problems is central to what we do, whether it is designing a seamless checkout or helping a colleague to make progress on a project.
Become an enabler
We all have been that first reviewer at a moment or another, and if you currently recognized yourself there here are a few tips for you:
Leave your ego out
If you comment on a pull request because it will make you feel superior to the submitter by showing how big is your knowledge relative to theirs or how you are the best developer there is, don’t. Just don’t. Especially if it does not bring any value to what he is trying to accomplish through the pull request. Always leave your ego out of anything if you want to be productive.
Close to the previous one even though one may happen without the other. Please do not assume one’s coding or design choices are wrong because they do not match what you would do. Ask questions and if there is a real issue try to provide comments that drive the submitter towards a solution.
When you request changes, depending on the system you are using you may be blocking a pull request and preventing someone from working. Make sure you follow-up whenever you can, between two of your own pull request submissions, during a coffee break or anytime you come back to your desk. Time is precious and when you request changes on a pull request you become responsible for the additional time spent on it for every developer involved.
Bring a positive value
Ask yourself about the impact you have on a project or a colleague. Does your comment make your colleague’s day better or worse? If it makes it worse, does it actually help solving the problem at hand and bring a positive value? Because at the end of the day, all that matters is the value you can create. Value to a business, value to people. Making a positive impact on your environment will encourage others to do the same. Eventually it will help you and the people around you to thrive and yearn for improvement every day.
Special thanks to Joshua Dooms who did make a positive impact on my vision of how reviews should go.