In my last article, I discussed how we can prepare our code to run effective code reviews, but that’s only part of the picture.
Many developers start their careers without really knowing what code reviews are for. We’re taught how to make code “work”, not how to work with others to make that code better. However, code reviews are not just about code, but also about team collaboration.
When used properly, code reviews can help us grow individually and as a team, while also improving the quality of our product. In this article, I will cover how.
Clear Communication
Usually, people are working in something else before they start reviewing our code. Their mind is likely somewhere else, and the context switch may take a lot of energy.
We already saw that we can write short pull request to aid with this, but we can also provide valuable context to our reviewers about the change that they are about to review.
When doing code reviews, people are usually interested in knowing why the change is needed, why a certain approach was followed, trade-offs, and so on.
At the very least, our PR should have a description, and it should clearly include that information. When that is not enough, we can rely on other common ways to convey this information, like inline or file comments, screenshots, videos and links to other sources.
Comments
Inline or file comments are useful to give general information that simplify the code review process. For example, we can tell when a file is autogenerated, as reviewers will often skip those. Or if a function is unexpectedly changed, explain why that was needed.
Normally, code should be self explanatory. If we find the need to explain our code in the pull request, maybe we should make our code more readable. When that is not enough, consider adding a comment in the code rather than in the pull request (but always use code comments as a last resort).
Screenshots
I find that the saying “an image is worth a thousand words” is particularly true when reviewing front end code, but I find that two images are even better.
Although I’m a backend engineer, I once made a very simple frontend change that consisted of wrapping a React component in another component. When raising the pull request, I added a screenshot of the UI before and after the change, to show that everything remained the same. However, this change unintentionally moved an element by one pixel, and the reviewer was able to spot this only because I added the screenshot.
Videos
Sometimes, when images are not enough, we can use videos. I find this really useful when we want to make sure that the intent of a pull request is very clear, or explain the problem that we were solving, where words or images are just not enough.
Sometimes it may be tedious to record a video, especially if we’ve never done it before. But this is a skill that can be learnt and used in other contexts, like doing async demos.
I find that videos are even more useful if we work with people across timezones. Sometimes we need to speak with someone to explain or talk about a pull request, and when that is not possible, video recordings are the next best thing.
You can learn more about working with remote teams in my article “Working across timezones“.
Links
Whenever relevant, add links to other resources like Jira tickets, confluence pages, or slack conversations. Sometimes these resources have a lot of relevant information that is worth making available.
However, we still need to add a proper description to the ticket. When we don’t, we force reviewers to click the links to get the relevant context that they need to help us. When we just add links, we waste people’s time, as they are now forced to follow those links to get the information that we should have given them.
I’ve sometimes seen pull requests that only have a link to a Jira ticket, and then the Jira ticket only has a link to Confluence. I find this really disrespectful to reviewers, as when we do this we’re saying that we don’t value the time they are spending reviewing our code.
Collaboration
Code reviews are all about collaboration. Nobody is right all the time. So it’s likely that our teammates will leave some comments in our pull requests, no matter how much effort we put in. And that’s fine, because code reviews allow us to learn through feedback, but this only works if we can be humble and open to changing our way of thinking.
Showing humility doesn’t mean blindly accepting comments. It means trying to understand other ideas, truly thinking about them, and deciding whether to accept them or not. If we still disagree, we should talk to our teammates with curiosity, trusting that everyone wants the best for the team, but that we may have different opinions of what that means.
Another way to collaborate is to ask questions. If we’re unsure about an approach or a pattern, we can ask in the pull request. If we’re really unsure, the best thing we can do is ask and get it right. Trying to merge code when we know it might be wrong is unprofessional and shows a lack of character.
And we can do this not only in our pull requests, but in any pull request. In fact, it’s our responsibility to review our teammates’ pull requests, even if they are more experienced than we are. Even if we don’t leave comments, we can still learn by seeing how others solve problems. When we don’t understand something, asking questions creates shared knowledge and makes future reviews easier. We don’t need to have all the answers to contribute. Just by being curious, offering suggestions, or asking for clarity, we help improve the code and our team.
Part of being a good collaborator is reviewing code in a timely and respectful way. We don’t always need to review straight away, but leaving others waiting blocks the team. We should also take turns and share the load so reviews don’t fall on the same people. And when giving feedback, our goal should be to help improve the code, not to blame anyone. Mistakes will happen, and what matters is how we learn from them together.
Final thoughts
If we all help each other, everything becomes easier. Code quality goes up, teams move faster, and we enjoy the work more. That’s why it’s worth learning how to do code reviews well.
So if you follow the guidelines I’ve just shared, I can assure you: your code quality will improve, your team will enjoy working with you, and you’ll grow professionally. Everyone wins when we collaborate effectively.
Our goal is to make the review process as easy as possible for our teammates, not to ourselves.
Cheers!
José Miguel
Share if you find this content useful, and Follow me on LinkedIn to be notified of new articles.