Mindful code reviews (Part 1)

Toxic vs mindful code reviews and why you and your team should care

Photo by Annie Spratt on Unsplash

Mindful code reviews

Think back to the last time you spent a lot of time working on a significant piece of a software project. You spent many days or even weeks working diligently on a strong code contribution to the team. You invested a lot of yourself - from the amount of time you put in, to the rollercoaster of emotions you felt, and some sleepless nights. The lines of code in your pull request represent your best level of contribution given the constraints under which you were provided.

On many software teams, the following scenario happens more often than any of us care to admit, and is the focus of this article. It's something that is very familiar, and yet, so many of us developers feel completely powerless to change.

What I'm talking about is a complete breakdown of effective and healthy human-to-human conversation during a code review. And even though it occurs randomly, it is preventable.

This article focuses on what happens during code reviews that become toxic and introduces what a mindful code review is.

Toxic code reviews

So what exactly is a toxic code review?

Anyone that's developed software on a team has experienced at least one toxic review. A toxic code review is the opposite of a mindful one. It's where one or more of the reviewers fail to think and treat each other as human beings full of complex emotions. Sometimes we treat each other like machines instead of as fellow humans. The toxic effects are most frequently felt by the person who requested the code review, but is often also felt by the other participants.

Setting the scene

Examples are always helpful, so let me create a fictional one that resembles many reviews that I've either experienced or observed while working with software engineering teams.

In this example, there are four developers on a software team:

• Kyle - a technical lead with 10 years of professional experience having worked on several teams at different companies

• Emily - a senior developer with 6 years of professional experience at 2 different companies

• Joris - a software developer with 3 years of professional experience having only worked for this fictional company

• Pierre - a junior developer on his first year of professional development having attended a coding bootcamp after a short career in marketing

Both Kyle and Emily work together in a US-based office but sometimes work from home. Joris and Pierre work 100% remote from their homes in Europe. The team has met each other in-person once before, but otherwise, haven't had a chance to interact and work side-by-side with the trust-building side effects of being in-person.

The team is currently focused on building a brand new web-based product with a common data-driven backend and frontend system. As a young startup that recently closed on series B VC funding, the team is on an aggressive schedule to release an initial product version and help the company scale. And because this is a young company, there are very few well-defined developer processes and documentation.

Sounding at all like your software team yet?

---

Subscribe to the Relational Technologist newsletter so you don’t miss any future software engineering career advice, technical guides and training/workshop opportunities.

---

Just another day of work

Being a new developer, Pierre often worries that he doesn't have what it takes to be a great software developer. Subconsciously, he's sensitive to the feedback that he receives about his work.

Pierre is tasked with building a piece of a new feature that his other teammates aren't yet familiar with, so they lack certain familiarity and context that Pierre understands.

After putting in nearly 2 months of work on this new feature, which the team estimated to fit within a single 2 week sprint, with hesitation and excitement, Pierre proposes a new pull request (PR) and asks for review from his teammates.

And this is when the toxicity in team communication starts to build...

Interactions with Kyle the tech lead

Kyle provides the first piece of feedback on Pierre's PR. While almost all of it was technically valid and useful, Kyle's responses caused Pierre to feel a lot of very difficult emotions. Pierre doesn’t quite know why, but he’s feeling a lot of hard emotions that cause him to doubt if he has what it takes to be on this team.

Let's look at some examples of the feedback he provided on certain sections of Pierre's code:

// ...

#[derive(Debug)]
struct Output {
    description: String,
    error: Option<reqwest::Error>,
    data: Option<Response>,
    threadId: ThreadId,
    debug: bool
}

// ...

pub fn print(&self) {
    if self.is_error() {
        self.print_to_stderr()
    } else {
        self.print_to_stdout()
    }
}

// ...

General PR responses:

• Context given via Slack: none provided

Overview comments in the PR response box:

1. Your code fails to follow the team's coding conventions. We use tabs, not spaces and we separate struct definitions out from main.rs and into appropriate other files (e.g. lib.rs)

2. Where are your tests? Every significant contribution requires accompanying tests!

Inline PR comments:

1. I prefer we rename Output to Log

2. Add a rustdoc comment that describes struct Output

3. threadId should use snake case and never camel case

4. Never expose in our own types any types used in development dependencies (e.g. reqwest::Error)

5. I prefer the use of match over if in print()

------

Pierre respects Kyle for his years of experience and depth of understanding. But he's also incredibly intimidated by Kyle for several reasons. First, Kyle has many responsibilities as tech lead which causes Pierre to assume that he doesn't have the time to prioritize helping him grow in his own programming skills. Second, the style and tone of Kyle's interactions always come off to Pierre as being cold and condescending. This makes Pierre assume that it's his fault and he's on his own to improve his skills. He worries about wasting Kyle's valuable time.

Interactions with Emily the senior developer

General PR responses:

• Context given via Slack: none provided

• Overview comments in the PR response box: none provided

Inline PR comments: none provided

------

The lack of feedback leaves Pierre feeling frustrated. Being a new developer learning Rust for the first time on a professional software team, he knows that his code leaves a lot to be desired. He wonders to himself "how will I ever improve on my development skills if I can't even get feedback from each of my teammates?" He also feels incredibly intimidated to ask for more from Emily so he says nothing further to her.

Interactions with Joris a peer and a friend

General PR responses:

• Context given via Slack: "Hey dude, I think you did a great job on this - it was not an easy feature to implement."

• Overview comments in the PR response box: none provided

Inline PR comments: none provided

------

Pierre and Joris consider each other friends and feel a certain affinity towards each other. Both live in neighboring EU countries and enjoy that they can speak their native language of French together.

Because they're friends, Pierre is able to give Joris the benefit of the doubt on his lack of PR feedback. But it still causes Pierre to feel even worse because he questions so many conflicting things:

• Am I valued on this team?

• Do I contribute more problems to the team than help the team in building great software?

• I made a career shift because I thought I'd enjoy being a software developer - maybe I was completely wrong about myself!

• I'm terrible at relating to other people - this confirms why I was never cut out for marketing!

Isn't this just how code reviews go?

For anyone who’s been a professional developer for long enough, I'm sure you’ve experienced a code review interaction like the one above.

Maybe you identify a lot with Pierre, you feel similar things that he did and you're frustrated. You feel small and you have no idea how to improve hard team interactions like the one above. And unfortunately, you don’t trust that your engineering manager knows how to either.

Maybe you relate more to Joris and you see a teammate of yours routinely suffering from their interactions with the team, but you have no idea how to help them.

You might relate to Emily who keeps her head down and tries to get as much of her own work done as possible. She doesn't really enjoy interacting with other people, so she tries to keep these interactions to a minimum. She's open to answering specific questions that her teammates ask of her, but otherwise, she lets others do most of the code reviews and conversations.

Perhaps you identify with Kyle and are a busy tech lead with a lot of important work that you're responsible to deliver. You can see some of how a developer on your team like Pierre struggles, but that's not your responsibility to fix - it's your manager's.

And isn't this just how code reviews go? Isn't this simply the nature of software development teams? We developers didn't pursue a career in software because we want to practice being great at interacting with other people. We got into it because we love technology, we love solving problems, and we love building amazing software systems!

Effective code reviews are mindful

What do I mean by "mindful?" One could certainly reference the dictionary definition of what mindfulness is, or read about it in articles like this one from Harvard, but here’s a more contextual explanation relevant to us developers performing code reviews.

Ask yourself - if you were one of the four developers participating in the code review on the fictional team described above, how aware would you be of what you want and need and what your teammates want and need during the review?

Or are you thinking: “It’s just a silly code review Jim! Why does anything relating to feelings, wants and needs have any relevance to a code review process?”

I’m really glad you asked that! 🍺🍺

Without being aware (i.e. another way of saying being mindful) of your emotional wants and needs and those of your teammates, you will not have as effective code reviews as you otherwise could. Let me repeat that: without awareness and more transparent communication of your emotional state with your teammates, the effectiveness of your code reviews will be sorely lacking. Not only that, you won’t build any trust with your teammates and even worse, you’ll actively destroy any existing trust.

Why?

Because all humans (you’re one of them!) are emotional beings first and foremost. We are not machines, even if we love working with machines. Even the most shy developer has complex emotional wants and needs and eventually needs to express them with other teammates to be an effective developer.

So when we participate in a code review in any capacity (whether it’s our PR or a teammate’s), we interact with our teammates first from an emotional lens, no matter if we’re aware of this lens or not. Our rational minds will only be effective in our communication for the code review if we’re mindful of our emotional state. When you become more mindful of this, you can communicate better what you need from others.

Next

In the second part of this series, I've invited a friend of mine, Andrew McLeod to go into greater depth on what mindful means and how to realize mindful code reviews on your team. He'll also provide ways for you and your teammates that greatly improve the quality of your team interactions and the effectiveness of your software delivery.

As always, a huge thanks for reading and passing this along to others who would enjoy reading the Relational Technologist.

You may find part two of this series here.

Please enjoy!

P.S. Are you and your software team experiencing toxic interactions during your code reviews or in other conversations?

I work with software developers and teams from around the world on improving how engineers both relate and communicate with each other. I can help you and your team greatly improve these areas as well, either in individual coaching or entire team sessions.

I’d love to show you how I can do that for you.