As a tech lead at rising fintech start-up PayMongo,

I’ve written hundreds of code reviews, spanning various codebases and dozens of engineers of varying seniority. My teammates will know that my reviews are especially comprehensive, and while comment count is hardly a measure of good code reviews, I’ve had at least a handful of teammates (and my managers) tell me that I give excellent feedback.

He writes excellent feedback!
—My manager/s at some point, definitely

Of course, being knowledgeable and keen on details are important to being good at code review, but I also take pride in being deliberate with how I deliver my feedback. After all, great code reviews are pointless if our teammates ultimately choose not to act on any feedback because they felt provoked by our tone or wording.

Here, I’ll be sharing a few of the techniques I’ve learned through the years so that you can begin to write code reviews that will help you build a positive and rewarding culture of feedback within your team.

Articulate your feedback as being a shared responsibility

Imagine your senior engineer just left you a code review. Which of these two comments would you be more receptive to?

🅰️ You should modify the API of this function.

🅱️ We should modify the API of this function.

How about these?

🅰️ You should follow the naming convention.

🅱️ Let’s follow our naming convention.

This one is unbelievably simple, yet incredibly powerful. We as humans are defensive by nature—and hearing you when we’re getting feedback tends to trip our wires for some reason. It feels as if we’re being singled out, or called out even.

Tweaking our language to emphasize that the feedback cycle is a collaborative process takes the heat away from the code author because it moves the spotlight away from them and shifts the responsibility towards the team as a whole. It’s also empowering to hear because it emphasizes the idea that we have a team to work through the feedback with and we won’t be going through it alone.

Try reading through comments you’ve left in the past and replacing any instances of you or your with we, us, or our. You’d be surprised by how much more collaborative you’ll sound.

Always assume your teammates wrote it that way for a reason

As engineers, we tend to want things to be as simple as possible, so when we write code, naturally, we try to apply just that. In practice though, there are almost always intricacies in our codebases that prevent us from writing code in the most reasonable or obvious way.

As a result, what we write can end up looking a bit odd to someone reading it without the context we’ve built while working through the spec. Inevitably, that can lead to comments that tell us we shouldn’t have overcomplicated Class A or Method B.

Instead, reviewers should assume their teammates’ best intentions and begin conversations with questions instead:

❓ Can you explain how we arrived at this solution?

(Also take note of the use of we.)

This gives our teammates a chance to provide context before we swoop in and suggest an approach they probably already tried (that didn’t work). Doing this allows us to empathize with our teammates’ approach first, before we can further explore how to devise a solution to the problem together.

If you don’t like beating around the bush and want to be more straight to your point, you can also preface your suggestion with a question:

❓ Would it have been possible to write it in this way instead?(Follow with your suggestion.)

It’s a bit more imposing, but leading our suggestion with a question gives our teammates space to feel like we understand that there might have been a reason they didn’t go with our suggested approach from the get-go.

Distinguish between blocking and non-blocking suggestions

Any engineer who’s worked a day in their life has gotten code comments that are ultimately trivial (i.e., non-blocking) in relation to the big picture. They can be annoying when we have bigger fish to fry, but they might still valid, so there is value in calling attention to a few nitpicks here and there.

My trick to get around the annoyance is to let the code author know I’m nitpicking. Doing this communicates to our teammates: “Hey, Miguel doesn’t think this is a big deal, so I won’t get too worked up about it because it’s not a big deal.”

Look at the difference:

🅰️ We can also build the string using template literals (`) for brevity.

🅱️ [NITPICK] We can also build the string using template literals (`) for brevity.

A simple indication like this makes our teammates feel like we acknowledge the way they wrote it (and that it’s perfectly fine!)—there just happens to be another way to write it that they might also want to consider.

Beyond just nitpicks though, I find that this also works when offering suggestions that are a matter of taste. We all have our own preferences, so acknowledging that up front before providing subjective feedback allows our teammates to feel that we’re not forcing our sensibilities on them.

Call out the good

When reviewing code, our brains are wired to find only faults. Not all code is bad. Far from it! If your teammate wrote a clever snippet of code or implemented a specific module brilliantly, write a comment to call it out!

🔥 I could not have written this any better myself!

Wouldn’t it be awesome to get feedback like this from your senior engineer?

There’s already enough negativity to go around in the workplace, so best to shake things up with a little positive energy when the opportunity presents itself. A short comment could turn your teammate’s day around if they’ve been having a bad one!

Sprinkle in some emojis ✅

Formal writing has a tendency to sound cold, so I find dropping an emoji or two usually allows my suggestions to sound friendly and unimposing.

🅰️ Did we still need to call this function?

🅱️ Did we still need to call this function? 🔍

Try it for yourself the next time you’re struggling to reword a comment to sound more accommodating. It could change the whole mood of your review! 😉

Just be sure not to overdo it. You don’t want to be that guy.

When we’re conscious about prioritizing collaboration over finger-pointing, we can turn code reviews into powerful tools for building a culture of growth and mutual respect within our teams. If you want that for your team, give your comments a review of their own before you next click ‘Submit review’. You might find you need to address some changes on your side first.

Remember, code reviewers are collaborators, not critics.

Happy culture-building!