Five stars code reviews
Pull requests are important, and code reviews are even more
Good review = Good code
Pull Requests (PR), or Merge Requests, are a must to maintain the code's quality. A pull request is a place where you can offer your code for review before it becomes part of your source code. A good review can be useful to find a bug that you missed or even to help you improve the readability of the code.
At New Work we have two mandatory code reviewers per PR. One is inside the team (or the code owner), and another is randomly by our custom script program.
This article is not about technical aspects or best practices, as this is something that each company owns, this article is about the importance of good feedback. By good, I mean valuable in any situation.
Start by creating a checklist for you to review each PR. Here is mine if you need some inspiration:
- 💅🏻 Coding style: The code must follow the code styling guidelines.
- 👓 Readability: By reading it, you should understand what the code is doing. A good naming of variables and functions is important to achieve it.
- 🔨 Maintainability: Code should be easily maintainable. For example, try to avoid leaving any magic number on the code.
- ✅ Test coverage: Don’t settle for the “tests have been added” check on your CI/CD system, sometimes we can forget to add tests for the logic we are making.
- 📝 Documentation: I��m not a documenting-everything-lover, if it’s self-explanatory it’s enough, but sometimes we sin by leaving important things without commenting on them. Take care of it in your reviews.
Let’s see this comment.
Looks pretty normal, right? Do you find anything wrong with it? Let’s discover how to improve it step by step.
⭐️ Be respectful with the time
If someone asks you to review a PR their workflow is in your hands, but that doesn’t mean rushing the review. Save time on your working days to do code reviews.
When you receive a pull request let the person know that you are aware of it, and tell them when you will review it.
Carla: Hey! I have this PR for you, please review the code when you have time 🙂
Mario: Sure! 👍🏻 I’ll review it at the end of the day.
⭐️⭐️ Give constructive feedback
Please, you don’t need to destroy your teammates! Help improve the code with respect, explaining why you suggest every change. No sarcastic words nor condescending ones.
The point of the review is not only to add value to the code but also to help the person who did it to understand why you think the change is needed.
⭐️⭐️⭐️ Be precise — use code proposals
The more specific the suggestion, the better. The most precise way to do it is to take time to improve the code by yourself. If you do a code proposal you will help your teammates to understand your point of view. If they feel that you are interested in their code, you are doing a good job. ☺️
Here is a secret Golden Rule: Don’t propose anything without testing it, make sure everything works!
⭐️⭐️⭐️⭐️ Don’t define — be open to discuss
Follow your feedback with an open question standing up to start a discussion. Do not define what the solution is, write your opinion and then try to reach a common point to solve the problem. Maybe both of you will learn something in the process 🤓
⭐️⭐️⭐️⭐️⭐️ Get the big picture
Focusing on single lines is good to improve readability and the coding style, but you need to get the big picture to understand what's going on. The scope of the source code is an extensive system of functionalities, not just what you are seeing on the bricks on the PR.
Do not ask anything that can be known having the context of the entire PR. One tip is to leave draft comments until you review everything, and then read again your comments, maybe some of them are already answered!
Many times a good review does not depend only on the reviewer, but also on how the PR is opened, but let’s leave that topic for another article, you already learned a lot today!
Thanks for the reading, and happy reviewing. 🤓
