{"id":602,"date":"2025-06-25T09:00:00","date_gmt":"2025-06-24T23:00:00","guid":{"rendered":"https:\/\/jm.armijo.au\/dev\/?p=602"},"modified":"2025-06-23T19:21:01","modified_gmt":"2025-06-23T09:21:01","slug":"collaborating-through-code-reviews","status":"publish","type":"post","link":"https:\/\/jm.armijo.au\/dev\/blog\/2025\/06\/25\/collaborating-through-code-reviews\/","title":{"rendered":"Collaborating Through Code Reviews"},"content":{"rendered":"\n<p>In my last article, I discussed how we can prepare our code to run effective code reviews, but that\u2019s only part of the picture.<\/p>\n\n\n\n<figure class=\"wp-block-embed is-type-wp-embed is-provider-practical-software-development wp-block-embed-practical-software-development\"><div class=\"wp-block-embed__wrapper\">\n<blockquote class=\"wp-embedded-content\" data-secret=\"2jzwYLXTE8\"><a href=\"https:\/\/jm.armijo.au\/dev\/blog\/2025\/06\/18\/preparing-for-effective-code-reviews\/\">Preparing Code for Effective Code Reviews<\/a><\/blockquote><iframe loading=\"lazy\" class=\"wp-embedded-content\" sandbox=\"allow-scripts\" security=\"restricted\" style=\"position: absolute; visibility: hidden;\" title=\"&#8220;Preparing Code for Effective Code Reviews&#8221; &#8212; Practical Software Development\" src=\"https:\/\/jm.armijo.au\/dev\/blog\/2025\/06\/18\/preparing-for-effective-code-reviews\/embed\/#?secret=D1LUUp8L9S#?secret=2jzwYLXTE8\" data-secret=\"2jzwYLXTE8\" width=\"500\" height=\"282\" frameborder=\"0\" marginwidth=\"0\" marginheight=\"0\" scrolling=\"no\"><\/iframe>\n<\/div><\/figure>\n\n\n\n<p>Many developers start their careers without really knowing what code reviews are for. We\u2019re taught how to make code \u201cwork\u201d, not how to work with others to make that code better. However, code reviews are not just about code, but also about team collaboration.<\/p>\n\n\n\n<p>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.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Clear Communication<\/h3>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>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.<\/p>\n\n\n\n<h5 class=\"wp-block-heading\" id=\"Comments\">Comments<\/h5>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>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).<\/p>\n\n\n\n<h5 class=\"wp-block-heading\" id=\"Screenshots\">Screenshots<\/h5>\n\n\n\n<p>I find that the saying \u201c<em>an image is worth a thousand words<\/em>\u201d is particularly true when reviewing front end code, but I find that two images are even better.<\/p>\n\n\n\n<p>Although I\u2019m 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.<\/p>\n\n\n\n<h5 class=\"wp-block-heading\" id=\"Videos\">Videos<\/h5>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>Sometimes it may be tedious to record a video, especially if we\u2019ve never done it before. But this is a skill that can be learnt and used in other contexts, like doing async demos.<\/p>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>You can learn more about working with remote teams in my article \u201c<em>Working across timezones<\/em>\u201c.<\/p>\n\n\n\n<figure class=\"wp-block-embed is-type-wp-embed is-provider-practical-software-development wp-block-embed-practical-software-development\"><div class=\"wp-block-embed__wrapper\">\n<blockquote class=\"wp-embedded-content\" data-secret=\"T2qRrGCHv5\"><a href=\"https:\/\/jm.armijo.au\/dev\/blog\/2025\/02\/05\/working-across-timezones\/\">Working across timezones<\/a><\/blockquote><iframe loading=\"lazy\" class=\"wp-embedded-content\" sandbox=\"allow-scripts\" security=\"restricted\" style=\"position: absolute; visibility: hidden;\" title=\"&#8220;Working across timezones&#8221; &#8212; Practical Software Development\" src=\"https:\/\/jm.armijo.au\/dev\/blog\/2025\/02\/05\/working-across-timezones\/embed\/#?secret=fDxHLbqLO3#?secret=T2qRrGCHv5\" data-secret=\"T2qRrGCHv5\" width=\"500\" height=\"282\" frameborder=\"0\" marginwidth=\"0\" marginheight=\"0\" scrolling=\"no\"><\/iframe>\n<\/div><\/figure>\n\n\n\n<h5 class=\"wp-block-heading\" id=\"Links\">Links<\/h5>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>However, we still need to add a proper description to the ticket. When we don\u2019t, 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&#8217;s time, as they are now forced to follow those links to get the information that we should have given them.<\/p>\n\n\n\n<p>I\u2019ve 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\u2019re saying that we don\u2019t value the time they are spending reviewing our code.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"Collaboration\">Collaboration<\/h3>\n\n\n\n<p>Code reviews are all about collaboration. Nobody is right all the time. So it\u2019s likely that our teammates will leave some comments in our pull requests, no matter how much effort we put in. And that\u2019s 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.<\/p>\n\n\n\n<p>Showing humility doesn\u2019t 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.<\/p>\n\n\n\n<p>Another way to collaborate is to ask questions. If we\u2019re unsure about an approach or a pattern, we can ask in the pull request. If we\u2019re 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.<\/p>\n\n\n\n<p>And we can do this not only in our pull requests, but in any pull request. In fact, it\u2019s our responsibility to review our teammates&#8217; pull requests, even if they are more experienced than we are. Even if we don\u2019t leave comments, we can still learn by seeing how others solve problems. When we don\u2019t understand something, asking questions creates shared knowledge and makes future reviews easier. We don\u2019t 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.<\/p>\n\n\n\n<p>Part of being a good collaborator is reviewing code in a timely and respectful way. We don\u2019t 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\u2019t 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.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Final thoughts<\/h3>\n\n\n\n<p>If we all help each other, everything becomes easier. Code quality goes up, teams move faster, and we enjoy the work more. That\u2019s why it\u2019s worth learning how to do code reviews well.<\/p>\n\n\n\n<p>So if you follow the guidelines I\u2019ve just shared, I can assure you: your code quality will improve, your team will enjoy working with you, and you\u2019ll grow professionally. Everyone wins when we collaborate effectively.<\/p>\n\n\n\n<p>Our goal is to make the review process as easy as possible for our teammates, not to ourselves.<\/p>\n\n\n\n<p>Cheers!<br>Jos\u00e9 Miguel<\/p>\n\n\n\n<p><em>Share if you find this content useful, and Follow me on&nbsp;<a href=\"http:\/\/www.linkedin.com\/comm\/mynetwork\/discovery-see-all?usecase=PEOPLE_FOLLOWS&amp;followMember=jmarmijo\">LinkedIn<\/a>&nbsp;to be notified of new articles.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"<p>In my last article, I discussed how we can prepare our code to run effective code reviews, but that\u2019s only part of the picture. Many developers start their careers without really knowing what code reviews are for. We\u2019re taught how to make code \u201cwork\u201d, not how to work with others to make that code better. [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":603,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-602","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/posts\/602","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/comments?post=602"}],"version-history":[{"count":1,"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/posts\/602\/revisions"}],"predecessor-version":[{"id":604,"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/posts\/602\/revisions\/604"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/media\/603"}],"wp:attachment":[{"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/media?parent=602"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/categories?post=602"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/jm.armijo.au\/dev\/wp-json\/wp\/v2\/tags?post=602"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}