The Impersonal Code Review
TLDR; a code review isn’t a comment on the quality of the programmer.
Software as a Craft
We often place personal stock in the work we do. This work will be reviewed at some point, be that by peers or customers. When comments are given, the criticism can feel like it diminishes or derides that work, and this in turn can be felt as an attack on the person rather than the work. That is, sometimes it is easy to see the valuation of the work we do as a valuation of our selves. This isn’t a very constructive way to work in a team.
I think part of the problem lies in the outdated naming of our field: “software engineering.” We all know what it means, but how many of us actually “engineer” anything? Think about a bridge: there are several engineers that will work on creating that bridge, and they’ll have spent a huge number of hours designing and explaining that bridge down to the smallest bolt, having several reviews and acceptance sessions before the first bit of that bridge is made.
That’s not how most of the software engineers I’ve worked with create code. If we built a bridge like we build software, we’d be pouring concrete on the first day. We work more like a sculptor does: they know what they need to do and how to do it, but it’s unlikely they’re going to sit down and draw up a set of detailed plans first; at most they’ll have a rough sketch of the idea. They’ll start the project, and to some extent allow the project to dictate the direction. That’s what I’d call “crafting.” If you look at what we do as an art or craft, it’s easier to see how we can put so much personal feeling into our projects.
Everybody’s a Critic
How many of us have looked at someone else’s code and found something we don’t like? Regardless of how well written, elegant, or efficient a piece of code is, there’s always something idiomatic that comes from the author of that code, their experiences, and opinions. Even something as trivial as the number of visual spaces in the indentation. Take a moment and make sure that statement didn’t raise your blood pressure.
Your reviewer undoubtedly has their own opinions on what is best, and most teams will have a style guide to help enforce a set of opinions. The person who reviews your code has a responsibility to point out where you’ve deviated from the house rules and where you might do something differently.
The Difference Between Critique and Criticism
The problem I had with reviews of my code was that I was viewing the comments as criticism rather than critique. Criticism has a negative association that is hard to detach. Critique doesn’t have that negative connotation. As an example, if a reviewer says “the indentation should follow the style guide”, as criticism could be taken accusingly: “why didn’t you read the style guide, dummy”. If you view it as critique, then you might receive it as “please review the style guide”, which is a much softer statement.
Understanding this difference marked an important point in my career. Switching my viewpoint on this took some practice, but had a remarkable side-effect: I realized that I wasn’t alone in building my code! I had a team, and they wanted to be helpful, not tear me down. By providing honest reviews of my code, they were helping me to hone my craft and become a more valuable part of the team. Not only did my code improve, but the harmony in my team increased. I just had to remember that a comment on my code was not a comment on my self.
Providing Conscious Critique
As important as it is to receive critique in an impersonal way, it’s also important to be aware of how you phrase your reviews of other’s code. My earlier example works well here as well. I’d never say “why didn’t you review the style guide” because that’s accusatory, vague, and unhelpful. I might be right in that the author didn’t review the guide, but insulting them isn’t helping anyone, and I didn’t actually state the problem. Instead, I might point out what part of the style guide was missed, and keep the words impersonal: “the indentation should be 4 space characters. <link to style guide>” That lets them know what the problem was and why I’ve provided that comment, and keeps the personal part out.
Keeping reviews impersonal and succinct should help the reviewee take it in the spirit of critique rather personal criticism.
Reviewing the Review
This might seem weird, but reviewing the review can be beneficial for both parties. Performing code reviews is a skill that requires practice and feedback.
When you review the reviews, the same viewpoint used for code reviews should be applied. These aren’t personal attacks, they should be intended to make you a better all-around team member. I’ve not seen anyone formally define a “style guide” for reviews, but I’ve often found anecdotally-shared guidelines inside of each team I’ve been on.
Practice Makes Perfect
You’ve crossed all the t’s and dotted all the i’s, you’ve tested it in every way you can think of, and now someone is going to get to second-guess all the decisions you made along the way. Let’s be honest, who remembers the why of every design decision in their code? Even if you’ve left a comment for yourself, that past you had context which may not have been included. And now your team gets to come in and point out all the ugly bits. Defense mode activated!
Remind yourself this is an important part of the process. Your teammates are here to help you, not hinder you. Repeat that mantra as needed.
My first team lead put a post-it on my monitor that read “it’s not about you” and would point at it when he saw me getting frustrated with a review. By the time it fell off my monitor, he didn’t need to point at it any more.
