As software developers, our work is constantly exposed to our teammates for review. This is a good thing! Code reviews (also known as pull requests) enable us to ship high-quality software. They also provide a real opportunity to teach and to learn from each other. Sometimes code reviews aren’t so positive. Negativity starts to color our way of approaching feedback, and the same people we love working with can start to seem like antagonists and disgruntled critics. This is not so great. It can get to a point where we feel exasperated, apprehensive, and resentful whenever we’re facing the prospect of a new code review. To engage positively in code reviews, it’s incredibly important to keep our empathy for our coworkers and our humanity at the forefront. We all care about learning and helping our teammates grow, and the words we use to facilitate that growth matter. If we can use the right words, the person we’re communicating with will see our true intent. The empathy and humanity we already have inside of us will come across loud and clear. We asked Engineers at Textio for ideas about how we can improve our code reviews, both from the perspective of the reviewer and the submitter. The ideas are collected below. ## As a Reviewer ------------- As a reviewer, think about what it feels like to submit a code review. You’re excited to have found a solution, and maybe a little apprehensive of what your teammates will think! As you engage with the code, keep the following things in mind: ### Understand what the submitter is looking for Sometimes the person who submitted the code review is looking for a quick sanity check of their logic. Other times, the submitter is asking for a check for how their code connects with the code around it. Sometimes, the submitter is interested in general feedback, and sometimes they’d like help with a specific area of code. Understanding what the submitter is looking for can help guide your response – if they’ve already gotten the perspectives they need, you don’t need to cover that ground again! If you’re not sure what the submitter is looking for, just ask! ### In-person is better When there’s something complex, challenging, or difficult that you’d like to work through with the submitter, an in-person discussion is often better than a wall of text on the code review. Speaking in-person reminds everyone involved that there’s a human on the other side of our communications and gives us the chance to have a real-time back-and-forth about an idea. If you find yourself taking more than a minute to express an idea in a code review, usually that’s a good sign that you should just pull the submitter aside. ### Don’t block unnecessarily This one is simple – if the comments you have don’t block the code from being merged, go ahead and approve the code review. Approving the code review communicates that your comments are non-blocking and shows your trust for the submitter’s ability to make their own decisions. Remember to block a code review only when you feel it’s truly important for the submitter to address your comments. In larger reviews, it can be helpful to focus mostly on the critical aspects to avoid overwhelming the submitter with feedback at various levels of importance. ### Explain the why If there is something you feel is important to address before the code review is merged, take the time to explain why. What thought process got you to your suggestion? Why will addressing your suggestion make the code better? How could the submitter think about writing similar code into the future? If you’re just telling the submitter what to do without explaining why, your suggestion can seem arbitrary or just a reflection of your personal taste. Explaining why can also uncover the times when your suggestion _is_ a personal preference! ### Talk about what you love As you’re reviewing a code review, remember to talk about the parts of the code you love. In general, most of the code you review will be good! When we focus on only the negative aspects it can have the effect of making the submitter feel unappreciated because they think that’s all you care about. The reality is you _do_ care about their great code, so be sure to let them know. ## As a Submitter -------------- As a submitter, having empathy for your reviewers can help quite a bit. Your reviewer wants to get up to speed with your code quickly and give you the input you need to get your code merged! As you start to write code to be reviewed, keep the following things in mind: ### Start the discussion well before submitting the code review Most complex code takes some architectural thinking or planning before we write the first line. Sometimes there’s a difficult decision midway through as well. We’re careful to think of everything, but the reality is that usually no one person can hold all the context to make great decisions in their heads. When you start to gain a point of view on a difficult decision or architectural plan, often it can be a good idea to consult briefly with the people who will be reviewing your code. Bring them into a room and share your plan with them. Your reviewers will appreciate being consulted! Often they’ll have ideas that will change how you think about the problem. These ideas will result in your solution being better, and you’ll all walk out of the room agreed to the plan. Gaining alignment on your approach to the problem early will set you up for success and a smooth review process later down the line. ### Give your reviewer the context they need It’s 9AM on a Monday and you’ve spent the weekend away from work. You open up a new code review and you’re greeted by a wall of code. There’s no description or comments, so you sigh to yourself and start to parse through what the code is doing. We’ve all been here. As a submitter, giving your reviewer the context they need to do their job well can make a huge difference both to the quality of the review and the quality of their lives. As you put together a code review for submission, try to make the answers to the following questions clear to your reviewers by adding comments in the code or on the review itself: * What problem does this code solve? If there’s an issue page tracking the problem, link to that issue in the code review. * What kind of feedback are you looking for from your reviewers? Is there a particularly tricky area you’d like to get extra attention? Are you looking for something high-level or something detailed and thorough? * What alternatives to this solution have you considered? Why did you choose this path? * What have you already planned to do into the future in this area of code? * How have you tested your solution? What do you expect from your reviewers in terms of manual testing? * What, if any, documentation have you updated to reflect the changes you’re making in this solution? Generally we like to have a template for our code reviews that summarizes these areas and helps us remember to include the right context in our submission. ### For larger reviews, give an in-person overview Even with all the context, sometimes a code review is just too large to quickly understand by yourself. As a submitter if you’re submitting a particularly complex or important code review it’s usually a good idea to preemptively set up a meeting to walk your reviewers through your code yourself. In this overview meeting, talk about how the code is structured, difficult decisions you made along the way, things you’re proud of, and things you’re interested in getting feedback on. Your reviewers will ask questions along the way and you’ll have the opportunity to answer them real-time rather than over the course of a few days via an extended textual back-and-forth. An in-person overview is a fantastic way to quickly get a room of people up-to-speed and ready to give you the information you need to get your solution shipped! Conclusion ---------- The ideas and guidance above really boil down to one clear idea: take care of your teammates in code reviews. Taking the time to think about setting our teammates up for success in their jobs as submitters and reviewers of code is something that helps all of us write faster, smarter software. By infusing empathy and humanity into our code review practices, we can make all of our lives a little more wonderful. #Evergreen #engineering