The Joy of Code Reviews
A lot has been said about code reviews, and the benefits for your team. More and more teams use them to improve their daily work and the quality of the code they write.
However, too many companies are still reluctant, and consider them time-consuming, underestimating the many advantages they bring.
This post describes the benefits of code reviews, and how at buildo we strive to make them as effective and effortless as possible.
What are code reviews and why should I bother?
Code review is the process by which every change to a codebase is subject to approval from other developers, that will review it, possibly requiring changes, before it’s merged into your main branch.
Having your code reviewed by other members of your team will dramatically improve the quality of your work in many ways. Here we’ll see the main advantages.
Boost your app’s reliability
It goes without saying: more people reading and testing your code before it’s merged means more bugs caught before they reach production.
Moreover, having multiple perspectives on a single issue means different (possibly better) opinions about your solution or the way you implemented it.
Share and validate your implementation choices, by having them reviewed
Shared guidelines
Code reviews are a good time to share guidelines between members of your team. Things like architectural design or the use of a particular library are shared among everyone. Your whole team will be aligned and can propose changes in case your code doesn’t meet the guidelines.
Furthermore, senior members of your team can take advantage of reviews to train less experienced developers or enforce coding style… although you should enforce as much as you can automatically ;-)
Code reviews are a great way to keep your team aligned
Shared code ownership
Code reviews will ease the burden of being the only developer in the world responsible for a particular piece of code, spreading the ownership and the knowledge across the team.
That particular feature you developed some weeks ago turned to be broken just before you’re leaving for holidays? You don’t have to worry about it anymore, since others can take care of it knowing how that code works.
Enforce code quality
Knowing that your code will be read and approved by someone else, you will start writing “for others”, always wondering if you are clear enough, adding better documentation and splitting your work into meaningful commits.
Remember: doing something in public makes it suck less.
Visibility is a great incentive for quality
But they’re a waste of time!!!
Yeah! That’s what you might hear from your managers, grumbling about decreasing throughput and velocity reduction.
But don’t let yourself be fooled! Code reviews don’t require a big effort if you’re able to master them, and the benefits will outweigh the extra work for sure.
Let’s see the best practices to get the most out of code reviews, and how in buildo we try to make them shine even more.
🔬 Keep changes small and readable
In order to ease the work of reviewers, every developer should keep changes small and well organized. Keep this in mind: if your work can be read quickly, your coworkers will be more willing to read it carefully. The review will take less time and it will be more effective.
Limit your code changes to what is strictly related to the feature you’re implementing, and organize them in meaningful commits if you think they could help better understanding your implementation.
Furthermore, if you think your code will take too long to be reviewed, try to split it in different review cycles.
📗 Document your code
This is not limited to comments in your codebase, but it’s more about listing the acceptance criteria, documenting the steps needed to test it and possibly including any additional snippet of code that could help speeding up the review process (e.g. mocked data or practical uses of your new component).
Adding a test plan describing the way you tested your new feature is a nice plus, even better if you contextualize your code adding screencasts, pictures or gifs.
⏰ Don’t postpone reviews
If someone requires a review from you, you shouldn’t delay it for too long. Keep in mind that the work of your teammates could be blocked waiting for your approval.
🔄 Establish a process to apply required changes
If someone required changes to your code during a review, you should apply them in clear and isolated commits. It will be easier for your reviewers to check them later, when they’ll review your code again.
For this reason, try to keep your commit history linear, e.g. avoiding rebases if you’re using git.
🛠 Carefully choose your tools
Over-the-shoulder reviews, emails exchange or pair programming sessions are all valid ways to make reviews, but you should carefully choose the tools that best fit your team’s habits.
If your teammates are generally busy with other tasks and it’s hard to find the time to be together at the same desk, tool-assisted reviews could be more appropriate, since they allow reviewers to schedule time for reviews independently and based on their personal commitments.
GitHub, with its pull requests, is a great example of code review tools, in particular after the recent introduction of “review requests”.
In buildo we go the extra mile!
Here at buildo we work hard at developing tools and processes that fit smoothly with our workflow and make our day-to-day work more pleasant.
Since most of our code is on GitHub, we built our review process around its “pull request” system, leveraging its APIs to improve the experience even more.
🔃 CLI ❤️ GitHub
While the GitHub web interface is well designed, as developers we mostly “live” in the terminal. That’s why we developed an internal CLI tool that supports us during the whole review process. Thanks to it, we can create branches for our new features and open PRs from them as fast as saying hophop [ndr. the italian equivalent forgo-go-gadget, from the 80’s animated tv series Inspector Gadget]
And, of course, we can’t call ourselves badass git users if we don’t use some fancy git aliases:
[alias]
feature = !hophop gh feature
pr = !hophop gh prBesides the speedup, you can use a similar tool to automate tasks and enforce guidelines, especially if supported by other scripts or tools. As an example, if supported by nemobot (our terrifying watchfish), our tool is able to automatically link a PR to the related issue, keeping them in sync and adding useful labels (like WIP or in review) to them.
Furthermore, it’s able to generate a default template for PRs (you can see an example in the GIF above) to remind developers to include any relevant information for reviewers (such as a test plan, a list of supported browsers, a link to the deployed feature, and so on).
🗣 Notify the reviewers
As we discussed above, it’s important to do your reviews in a timely fashion, so as to avoid blocking your teammates.
For this purpose, a notification system could come in handy, reminding developers of pending reviews.
At buildo we use bitbar, a tool that lets you show the output of any script right in your Mac OS X menu bar. We added some ad-hoc scripts to show the number of pending reviews: thanks to this, requests for review will no longer be missed!
Conclusions
To recap, code reviews will bring a lot of benefits in your daily work and a relevant improvement in the quality of your final product.
If done right, they don’t require a lot of effort. In fact, they often decrease the time spent in finding bugs, late refactoring, knowledge sharing and handovers.
Also, with little additional work, you can fit the review process to your needs, automating the most critical aspects and enforcing guidelines to get the best out of them.
So, if code reviews are still not your bread and butter, try to figure out the best way to bring them to your team, you won’t regret it!
Happy reviewing ;-P
—
If you want to work in a place where we care about the quality of our development workflow, take a look at https://buildo.io/careers
