Leveling up your code reviews
or, all the baggage and distrust engineers carry with them
Code reviews are ripe for miscommunication and deteriorating trust. 99% of the time, the only comments left are “negative,” pointing out something to change, or expressing concern or uncertainty with an approach. Engineers also carry a lot of past experiences with them that they can project onto what’s going on now. Without a foundation of trust between the reviewer and coder, code reviews can be interpreted way worse than they were intended — much more often than they are interpreted way better than intended! Here are some common patterns…
The questioning — “Why did you choose to implement it this way?”
Best interpretation: “Wow this is super elegant, I’m genuinely curious how you decided to go this route.”
Worst interpretation: “Why in the world would you choose to do it this way?! You’re such an idiot and a terrible engineer.”
The terse comment/emoji — “syntax”
Best interpretation: “I trust that you know exactly what I’m talking about with the indentation not conforming to the style guide.”
Worst interpretation: “I can’t believe you can’t even follow a simple style guide and wasted my time with this.”
The vague ask — “This should be refactored to follow this new convention”
Best interpretation: “Just FYI, you totally don’t have to do it in this change, but at some point we should upgrade this bit of code, for consistency! Maybe I’ll do it after you merge this.”
Worst interpretation: “Do not even think of merging this code without also refactoring this whole file. Does NOT look good to me.”
The many-commented review
Best interpretation: “I care a lot about your work, so I spent a lot of time going over it carefully and hope it’s super helpful to you. Overall, this is great work, but I left a bunch of comments on minor issues. Feel free to merge it whenever you address them — I don’t need to take another look!”
Worst interpretation: “Your code has so many issues I can’t even. It’ll probably take days and many full refactors to get this in a state that is even acceptable.”
What to do?!
Code reviews are tricky. Here are some techniques I found to be useful in building some positive sentiment.
Say thanks
Find something to thank the engineer for. Thank them for refactoring something and making the codebase better. Or thank them for getting something hooked up quickly so that others are unblocked. Or thank them for keeping the change small so that it’s easy to review. Say thanks for anything you want to keep happening, and people on your team are more likely to keep doing those things!
Leave a compliment
People are used to code reviews feeling negative or at best, neutral. Most people only leave comments about things that might need to change. Be the person who says something like “Wow this is super elegant and simple and I wouldn’t have thought to do it this way” instead of just glossing over it because there’s nothing wrong.
Contextualize
A comment that says “Left some minor comments, LGTM when they are fixed!” goes a long way. Before github had “reviews,” I really didn’t like that it emailed on every comment because it can be anxiety-inducing to see a ton of comments roll into your inbox and not know when it will end. Packaging all of them up into one review makes it easy to have a general comment to contextualize.
Take it offline
Especially for a new hire or intern, the anxiety of doing a code review that’s public to the whole team is real. If you’re asked to do a code review that requires major changes or lots of small changes, consider pinging the engineer and say “Hey I think it’ll be easier to sit down and go through it together” and go to their desk or book a conference room. As long as you’re not condescending, an in-person pairing and review session will save both of you time.
Build trust
It can take many interactions and the passage of time for trust to build between two individuals. As a reviewer, you may ignore someone’s code review request because they always open large unpolished pull requests. Be prompt in doing code reviews, even if that means saying “Hey this is really long, can you break it up and let me know when it’s ready to review?” or “I noticed a lot of style inconsistencies — can you go over the style guide and fix those before I take a look?” instead of ignoring it altogether. With one specific engineer I started sending pull requests to, his code reviews went from lots of comments to literally an LGTM 30 seconds after I opened the pull request — our expectations had aligned, and he had seen enough examples of similar changes from me that all it took was a quick skim before approving. Once we had built a foundation of trust, I knew I could get my code reviewed quickly.
Code reviews are a two-way street. Here are some tips on leveling up when you’re the engineer asking for a code review.
After many years working full-time at tech companies, I’m now coaching and consulting engineering teams. If you’d like some help scaling your team or developing yourself as a leader, email me at jean@jeanhsu.com.
