Level up your code review
A simple handbook of 5 non-written rules for reviewing a pull request
I still remember the first pull request back in my internship time and exposing code to others. I would take a pen, paper and write every suggestion I got from my mentor. Single review used to last for days, and at that time, I used to think how terrible this part of my work was.
For junior developers, the review can either be a learning place or a wall of shame. It’s up to the team and seniors to bring an atmosphere of trust, honesty, and constant improvements. In simple words: If the review process is a learning space and ego-free, the team is happy, and individuals are growing.
Years of experience don't guarantee the quality of code is perfect. Junior developers should be empowered to review senior developer's code, and if they don’t understand changes, pull request needs some major improvements.
Different teams have different policies and norms when it comes to reviews. However, as a mature developer, there are some non-written standards that you should consider adopting.
1. Don’t let emotions drive your reviews
There are bad days and good days for everything we do. Humans are sensitive; developers are humans. It’s up to us to be self-aware and recognize when we feel low, angry, or just distracted.
If you don’t have a concrete solution or alternative, better don’t comment at all. If you feel angry or stressed, it’s better to postpone your review for later.
2. Think about the context
No pull request should be reviewed without considering the bigger picture.
When it’s the deadline? Is this a hotfix? Who created a pull request? How big is the change? There are many things to consider when reviewing someone else code. If we’re late to deliver, it’s better to create a tech-debt ticket than spent hours on optimization. I’ve often seen how bad review leads to over-optimization, and over-optimization leads to our code not being readable or even introducing new bugs.
Always look for better solutions, but don’t forget to deliver
3. Be kind and provide solutions.
To make a pull request learning spot and place where developers feel free to share their opinions and express themselves, we should always be kind. Kindness drives others to be kind as well, and that’s what stimulates trust in a team.
Providing solutions instead of criticizing is a better way of leading less experienced team members. Commenting on PR without a real purpose or solution is most of the time nitpicking.
Review is not a place to show how smart or you are; it’s a place where we make our code better, fix issues, and find alternative solutions.
4. Always be truthful.
Not being truthful can cause more damage to the team than declined pull requests and missed deadlines. Hiding things in software development is one of the worst things you can do. Most of the time, hiding the truth besides creating a new bug destroys trust between team members.
Instead of hiding potential bugs, we should let others know what’s going on and create a tech-debt ticket or just a simple TODO comment in our code editor.
5. Find your process.
There is no perfect process for reviewing PR’s, but better to have your own than not having a process at all. The individual reviewing process should always be aligned with the team norms.
Always have a checklist: This doesn’t need to be a handwritten checklist, but rather a set of reviewing premises.
Here is my review process:
1. Check for a commit message, title, and description
2. Look for bugs and code smells
3. Test the actual feature
4. Look for improvements and edge-cases
Pull request review is a place where developers are vulnerable, and we should always be aware of that. It’s not a place to show how smart you’re but rather how we can improve our code.
Reviewing is not about writing 100 comments. It’s about meeting team goals and finding a better way of doing things.
Always look for improvements and alternative solutions, but never forget the aim.