Blog Feed Post

Better Code Reviews Through Empathy

better code reviewshttps://www.pagerduty.com/wp-content/uploads/2017/04/bettercodereview-30... 300w, https://www.pagerduty.com/wp-content/uploads/2017/04/bettercodereview-76... 768w, https://www.pagerduty.com/wp-content/uploads/2017/04/bettercodereview-25... 250w, https://www.pagerduty.com/wp-content/uploads/2017/04/bettercodereview-18... 180w, https://www.pagerduty.com/wp-content/uploads/2017/04/bettercodereview.png 1518w" sizes="(max-width: 452px) 100vw, 452px" />Code reviews are an important part of the modern software lifecycle. Unfortunately, a lot of cycles are burned and morale is damaged because there are few guidelines given to reviewers (and reviewees) on constructive feedback and effective written communication. Below are some tips for a better code review process.

Determine why you do code reviews

Is it to find bugs? Is it to spread knowledge of the codebase? Is it to find architectural problems? What do code reviews offer your team? If you don’t know the answer to this question, you don’t know how well they’re working.

It’s probably best to have this explicit conversation with your team. It’s OK that teams use them for different things, but it is very important that both the author and reviewer know what the expected outcome of a review is.

Within our team, I expect that I’m sharing code mostly to spread knowledge of changes to codebases, and as a sanity check that I’m doing nothing incredibly stupid. Sometimes I will need expert guidance (for example, in front-end work, or in services that I rarely poke around in). Usually, I try to get this before tagging someone in a PR. When this happens, I think it is best to acknowledge explicitly that you’re expecting that person to be the expert, so that they can take a closer look and perhaps help you with a deploy.

Automate your style guide

If the answer to, “why you do code reviews” includes, “making sure the code follows a consistent style,” cut it out. It’s difficult to review code that is poorly formatted. And it’s really, really tough to review code for both correctness and style without making multiple passes. It’s also really demoralizing to new engineers on a project to look at their PR and see dozens of style comments. Great automated style tools exist that can automatically style your code and you should use these. On my particular team, we strive to use Scalariform for our Scala stuff and Rubocop for our Ruby projects. Under no circumstances in 2017, should engineers be manually fixing formatting issues.

As a fallback, in cases where automation has not been set up, it’s best for the reviewer to correct the formatting themselves instead of adding comments to the author (this is doubly true when you are reviewing code for your own teammate). Small things can be handled directly in the GitHub UI and we shouldn’t be shy about adding a few pointless commits that’ll be squashed down before merging anyway.

Offer suggestions, not orders

Don’t tell a committer how they’ve done a thing incorrectly in a code review remark. Offer a suggestion, and ask what they think of it. For example, take a look at the comments below:

Don’t repeat this here, extract a function.

This clearly feels very negative. The author may feel defensive and start a pointless argument, even if there are few benefits to doing so; or worse, the author may feel like a less valuable contributor, and follow the suggestion blindly. In either case, actual harm is done by comments like this.

The best thing you can do is to offer a suggestion, not as a gatekeeper, but as someone who is trying to learn about the changes to the code (even if you really are a gatekeeper).

What do you think about taking this with the above and extracting a function?

Why should you make your comments sound so tentative? Because you are reviewing your peer’s code. You have to invite them to politely explain what’s going on, or to notice that you’ve made a better suggestion. Having no manners in this regard eliminates the possibility of discussion for a significant segment of the population.

Let’s talk about my number one pet peeve in code reviews…

Why didn’t you…

Asking a “why didn’t you” question implies a great many things, none of which are constructive or positive. It assumes that the author of the code has previously considered your suggestion and explicitly chose a different one, which may not be the case. It implies that your alternative is obviously superior (especially in the special case of “why didn’t you just…“), and that you require that the author justify their solution against it. It implies that what may be intended as a mere suggestion is, in fact, the default.

Whenever I am reviewing code and my hubris needs to be checked, I try to offer a suggestion. “How do you feel about…” or “what do you think about…” are good drop-in replacements for this phrase.

Use overtly positive language

It is important to recognize that written communications have a profoundly negative bias. We tend to interpret neutral communications as negative, and positive communications as neutral, which is a source of a lot of consternation in code reviews. To combat this, strive for overt positivity.

Terseness can be interpreted as rude or inconsiderate. In particular, avoid adding a two or three word comment.

Use code reviews as a learning exercise

My genuine unsupported-by-data opinion is that code quality and correctness are only marginally improved by having a code review by a gatekeeper. It is rare that a reviewer shares the same level of insight as the person who authored the code (well, except in the aforementioned, “review by expert”). A better model is to have code reviews treated as a learning exercise for the reviewer, i.e. to understand the changes to the code and to grow in understanding of the code base. I think this leveling gives their questions and remarks appropriate weight, and allows for a healthier discussion about the larger codebase and how the changes interact with it.

Of course, you don’t have to do any of that to be nicer in your reviews.

When receiving a code review

For receiving a code review, you should follow the same suggestions in reverse. Recognize that terse comments don’t mean the reviewer thinks less of you. Recognize that “orders” are usually just poorly-phrased suggestions, and an invitation for you to think about the problem a (potentially different) way. Recognize that pretty much everything written comes off more negatively than intended, and give a lot of leeway to your teammates.

It’s easy to imagine that brutal code reviews are a ritual that leads to the best outcomes. In my experience, engineers are a lot more sensitive to criticism than they let on, and they are a lot more willing to be found wrong if they feel like collaborators rather than defendants. Take a few extra minutes to add some kindness to your reviews, and I think you’ll find your reviews are a lot more productive and leave you feeling better at the end of the day.



*This post was originally featured on Cory Chamblin’s personal blog. We thought it would be helpful to our blog readers, so we decided to share it here as well.

The post Better Code Reviews Through Empathy appeared first on PagerDuty.

Read the original blog entry...

More Stories By PagerDuty Blog

PagerDuty’s operations performance platform helps companies increase reliability. By connecting people, systems and data in a single view, PagerDuty delivers visibility and actionable intelligence across global operations for effective incident resolution management. PagerDuty has over 100 platform partners, and is trusted by Fortune 500 companies and startups alike, including Microsoft, National Instruments, Electronic Arts, Adobe, Rackspace, Etsy, Square and Github.

Latest Stories
Translating agile methodology into real-world best practices within the modern software factory has driven widespread DevOps adoption, yet much work remains to expand workflows and tooling across the enterprise. As models evolve from pockets of experimentation into wholescale organizational reinvention, practitioners find themselves challenged to incorporate the culture and architecture necessary to support DevOps at scale. In his session at @DevOpsSummit at 20th Cloud Expo, Anand Akela, Senior...
Join IBM November 2 at 19th Cloud Expo at the Santa Clara Convention Center in Santa Clara, CA, and learn how to go beyond multi-speed it to bring agility to traditional enterprise applications. Technology innovation is the driving force behind modern business and enterprises must respond by increasing the speed and efficiency of software delivery. The challenge is that existing enterprise applications are expensive to develop and difficult to modernize. This often results in what Gartner calls ...
In recent years, containers have taken the world by storm. Companies of all sizes and industries have realized the massive benefits of containers, such as unprecedented mobility, higher hardware utilization, and increased flexibility and agility; however, many containers today are non-persistent. Containers without persistence miss out on many benefits, and in many cases simply pass the responsibility of persistence onto other infrastructure, adding additional complexity.
Did you know that you can develop for mainframes in Java? Or that the testing and deployment can be automated across mobile to mainframe? In his session at @DevOpsSummit at 20th Cloud Expo, Vaughn Marshall, Sr. Principal Product Owner at CA Technologies, will discuss and demo how increasingly teams are developing with agile methodologies using modern development environments and automating testing and deployments, mobile to mainframe.
SYS-CON Events announced today that Hitachi Data Systems, a wholly owned subsidiary of Hitachi LTD., will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City. Hitachi Data Systems (HDS) will be featuring the Hitachi Content Platform (HCP) portfolio. This is the industry’s only offering that allows organizations to bring together object storage, file sync and share, cloud storage gateways, and sophisticated search an...
With major technology companies and startups seriously embracing IoT strategies, now is the perfect time to attend @ThingsExpo 2016 in New York. Learn what is going on, contribute to the discussions, and ensure that your enterprise is as "IoT-Ready" as it can be! Internet of @ThingsExpo, taking place June 6-8, 2017, at the Javits Center in New York City, New York, is co-located with 20th Cloud Expo and will feature technical sessions from a rock star conference faculty and the leading industry p...
@GonzalezCarmen has been ranked the Number One Influencer and @ThingsExpo has been named the Number One Brand in the “M2M 2016: Top 100 Influencers and Brands” by Analytic. Onalytica analyzed tweets over the last 6 months mentioning the keywords M2M OR “Machine to Machine.” They then identified the top 100 most influential brands and individuals leading the discussion on Twitter.
Automation is enabling enterprises to design, deploy, and manage more complex, hybrid cloud environments. Yet the people who manage these environments must be trained in and understanding these environments better than ever before. A new era of analytics and cognitive computing is adding intelligence, but also more complexity, to these cloud environments. How smart is your cloud? How smart should it be? In this power panel at 20th Cloud Expo, moderated by Conference Chair Roger Strukhoff, pane...
Most companies are adopting or evaluating container technology - Docker in particular - to speed up application deployment, drive down cost, ease management and make application delivery more flexible overall. As with most new architectures, this dream takes a lot of work to become a reality. Even when you do get your application componentized enough and packaged properly, there are still challenges for DevOps teams to making the shift to continuous delivery and achieving that reduction in cost ...
The Internet of Things is clearly many things: data collection and analytics, wearables, Smart Grids and Smart Cities, the Industrial Internet, and more. Cool platforms like Arduino, Raspberry Pi, Intel's Galileo and Edison, and a diverse world of sensors are making the IoT a great toy box for developers in all these areas. In this Power Panel at @ThingsExpo, moderated by Conference Chair Roger Strukhoff, panelists discussed what things are the most important, which will have the most profound e...
SYS-CON Events announced today that Twistlock, the leading provider of cloud container security solutions, will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Twistlock is the industry's first enterprise security suite for container security. Twistlock's technology addresses risks on the host and within the application of the container, enabling enterprises to consistently enforce security policies, monitor...
@ThingsExpo has been named the Most Influential ‘Smart Cities - IIoT' Account and @BigDataExpo has been named fourteenth by Right Relevance (RR), which provides curated information and intelligence on approximately 50,000 topics. In addition, Right Relevance provides an Insights offering that combines the above Topics and Influencers information with real time conversations to provide actionable intelligence with visualizations to enable decision making. The Insights service is applicable to eve...
The age of Digital Disruption is evolving into the next era – Digital Cohesion, an age in which applications securely self-assemble and deliver predictive services that continuously adapt to user behavior. Information from devices, sensors and applications around us will drive services seamlessly across mobile and fixed devices/infrastructure. This evolution is happening now in software defined services and secure networking. Four key drivers – Performance, Economics, Interoperability and Trust ...
Multiple data types are pouring into IoT deployments. Data is coming in small packages as well as enormous files and data streams of many sizes. Widespread use of mobile devices adds to the total. In this power panel at @ThingsExpo, moderated by Conference Chair Roger Strukhoff, panelists will look at the tools and environments that are being put to use in IoT deployments, as well as the team skills a modern enterprise IT shop needs to keep things running, get a handle on all this data, and deli...
SYS-CON Events announced today that Grape Up will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place on Oct. 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Grape Up is a software company specializing in cloud native application development and professional services related to Cloud Foundry PaaS. With five expert teams that operate in various sectors of the market across the U.S. and Europe, Grape Up works with a variety of customers from emergi...