Six (more) best practices to improve your code review
Code reviews are (still) complex. We started this series here, and we are back now to complete it with six more recommendations.
1. Stick to the point
There is a school of thought that recommends creating very broad and ample pull requests that will encompass a variety of issues and promote a more thorough review. We don’t share that idea. Development is a fast-paced environment and code reviews should be continuous and integrated into the dev process. That means pull requests need to be specific and as clear as possible to the reviewer, so that communication is as seamless as possible.
2. Focus more on questions than answers
We believe in co-ownership of the codebase. That means the reviewer and the original developer are cooperating on a project that is of both their responsibilities.
The reviewer isn’t “fixing” their colleague’s “mistakes” any more than the developer is being evaluated.
What’s happening is a dialogue, a collaboration that will improve the quality of the codebase. That means that when you find an issue, or something you don’t entirely agree with, it may be more interesting to make suggestions, or question why the developer made that choice, instead of simply stating a fix that may not fully fit the original intent of the code.
3. Impact matters much more than the size
While some may recommend that any change warrants a full review, or that every change must be manually reviewed, we don’t think that’s the way to go if you are getting familiar with the code review process.
If you replace the name of a variable, it hardly matters that you have changed fifty files or five. You know exactly what you’ve done, and automation ensures that there’s no point whatsoever in checking every instance of the change.
What matters is when you’re making conceptual changes.
4. Clearly label changes that aren’t conceptual
This stems from the previous point. If all you’re doing is fixing a bug, or changing a small detail that is self-contained and doesn’t affect the rest of the codebase, it’s very useful to make that clear for your colleagues.
A small note indicating clearly that “this change here is separate from everything” and explaining your train of thought and reasoning will go a very long way in avoiding roadblocks.
5. Speak up to improve the process
What if you usually allocated half an hour for code reviews in the past, but now you’ve become better, started seeing more issues, and now you need more? Speak up. What if you used checklists when you were a junior developer and reviewer (a good idea) to make sure you didn’t miss anything, but now you feel like they are getting in your way? Speak up. What if you feel like an inadequate amount of conflicts are being generated by code reviews? Speak up.
It’s very important to not let so-called “best practices” get in the way of actually doing good work. Teams are different, and what is helpful for people with different skill sets and levels of experience is also different. If something isn’t working, it needs to be changed.
6. Talk to people directly
Code reviews are not a place for conflict. They’re not a conflict resolution tool. You should be writing code you can defend but you shouldn’t need to be on the defensive.
Positivity in the review itself, and keeping things as light-hearted and communicative as possible will help with this. Making sure the reviewer and the developer understand they are co-owners of the same thing and not competitors too.
The one thing that almost always fixes things, however, is a good old-fashioned conversation. If you move the review from async comments to a synchronous discussion, most gritty misunderstandings and tonal difficulties will evaporate in no time. This will not only protect your team from a lot of mental wear and tear, but it will actually save you plenty of time in useless back and forths in the comments.
Just talk to your teammates.
These are our recommendations
What did we miss? Is there a particular issue that you feel helped your team immensely that we didn’t cover? Are we wrong about any of this?
We’d love to hear from you. Just follow us on Twitter (@codereviewpad) and drop us a line.
