Code review is an engineering practice where you open your changes to your teammates so that they review, validate, and make suggestions to them in order to improve their quality.
At Belvo, it’s one of the most important things that we engineers do. And we care about doing it well! That’s why we recently organized an internal team training from where we’ve extracted a set of best practices and recommendations that we share on this post.
Reviewing our code helps us build software that guarantees quality and excellence. An awesome additional benefit of it is that we use it as a tool to spread knowledge among team members. Something that we need to remember right from the get-go is that if we have more than a pair of eyes looking at our changes, it’s easier to avoid bugs at the early stages. Thanks to this, we can learn as well as implement newer, and at times better, approaches. Code reviews allow us to run faster, or sometimes even realize that our changes aren’t needed anymore, letting us close topics and move on. But of course, it all starts with the developer.
You painstakingly implement your solution and test it to such a degree that you feel comfortable letting the world (that is, your teammates) see it. And now, you’re ready to push a Pull Request (PR) for peer review.
Preparing your PR
Something that you have to remember when preparing your PR: not everyone will know the context of your changes. Your reviewers could be from different teams, work in a different tech stack, or maybe for some reason they’re not even developers (and for some reason you’ve included them as a reviewer, but we don’t judge). As such, it’s your responsibility to be as clear as possible about what you’re changing, why, and how.
Knowledge sharing
We find that the PR summary is also a great place for knowledge sharing among developers. For example, if you are fixing a bug, you can post links to the relevant pages where you add information about it or links that go deeper into the approach you take. Of course, you are more than welcome to write the explanation in your own words, just to make sure that you, and your readers, fully understand why and how these changes were made.
By having descriptive PR summaries, in the future, you or your colleagues can come back to the PR and use it as a reference about how that particular thing was added, changed, or fixed. The benefit? Well not only can you avoid some double work regarding research, but also you can speed up the development of your colleagues.
PR tips for writing a summary and title
The PR summary is the text box you can fill when you open a new PR. Here, you should add as much relevant information as you can. To help you on your way, we’ve created a couple of Dos and Don’ts:
❤️ DOs
Really make sure that the summary content:
- Explains what you are adding or changing
- Why you are doing it
💔 DON’Ts
Try to avoid:
- Mysterious titles that don’t provide any benefit
- Writing one word to explain the entire PR
- Assuming that all the reviewers have the entire context of these changes
- Writing nothing at all
Once you have opened your PR and explained everything that is relevant in the summary, the fun begins: giving and receiving comments! 🚀
Giving and receiving comments
So you’ve got your solution, you’ve written your summary, and now it’s time to let others review your beloved code by giving and receiving comments or suggestions (sometimes the most dreaded part of software development actually). However, no matter if you’re the author or the reviewer, follow these tips and you will see that this process isn’t so bad after all:
This is not a personal matter 👉😕
Giving or receiving feedback shouldn’t be taken on a personal level or viewed as a personal attack. Instead, make sure you keep things professional and that your feedback is constructive and actionable.
The review is for the code, not of the developer.
Respect 😌
You are talking to a teammate, and before that, to a person, so you must be respectful at all times. No disrespectful behavior should ever be tolerated.
Embrace different opinions 👂👀
We all invest a lot of time thinking and developing a solution until we are happy with the result, and reviewers asking us to change things we thought were OK (or even “the best line of code ever developed”) can be annoying sometimes.
But don’t get frustrated or lose hope! Your colleague is trying to help, so just open a conversation between the two of you. It will help you both understand each other’s point of view.
Justify your suggestions 🧐
If you are making a suggestion for a change, explain why you think that approach is better than the original one. We really discourage reviewers from asking the author to make a modification without explaining the reasoning behind it.
Don’t be shy 😄
Sometimes, developers think they don’t “rise to the challenge” to leave a comment on a “more experienced” colleague’s PR and just leave it. Or worse: they accept the PR without looking at it at all.
Even if your suggestion is for a typo or a missing comma, if it makes sense, DO IT! Nobody will laugh or ignore you. On the contrary: the author will either thank you for noticing or explain to you why the change here isn’t necessary (if that’s the case). In the first case, your confidence shoots up. In the second case, you become a better developer thanks to the new knowledge.
Include positive feedback 👍❤️
Don’t forget that giving positive feedback is also important. As a reviewer, you might be tempted to only highlight what should be changed or improved in the code, but it is also important to point out the good things in the code and let the author know about them with a positive feedback comment.
Sync your async chats 👩💻👨💻
Async conversations, as in reviews, are great but sometimes they are not enough. Going back and forth with a review is far from being ideal, it delays the PR resolution, takes time from both the author and reviewers and creates annoying context switching.
If the review is not going smoothly because of the amount of PR comment threads, just ping the reviewer talk face to face (or rather, via video chat these days) to resolve any doubts more effectively.
But, one important thing to remember is: once you have finished this conversation, go back to the PR and write down your takeaways in the original conversation thread so you let the other reviewers, and future visitors of the PR, know which were the decisions taken and why.
Code reviews are one of the many core elements of software development and working among teams. Yeah, it’s true that sometimes it’s considered a difficult and slow process. But, at Belvo we’ve found that with the right conventions, best practices, tools, and team commitment, it gets smoother and smoother, allowing the entire team to develop faster, minimize bugs, and learn.
And remember: always keep it relevant, short, and clean.
Psst, psst, our team at Belvo is growing fast! Take a look at our careers page if you’re interested in joining us.
Chelo Romagnoli is a Backend developer at Belvo’s Engineering team.
