EM's Guide For Not Being The Worst In Your Next Code Review
You might be coming off as a jerk in your code reviews and not even know it. That's exactly why I wrote this guide and exactly why you need to read it.
Too often, people just get it completely wrong. Whether it's deliberately being a complete jerk, or unintentionally ruining your engineer's day, PR/Code reviews are one of the easiest ways to make enemies. I've been there before, too many times, so that's why I wrote this guide for not being the worst in your next code review.
🖼 Code Is Sacred Art
There are exceptions to everything, but I maintain that every time an engineer picks up a ticket, they pour their heart out into the codebase. Code can be like painting in that there are often multiple ways to solve a problem. This is why code reviews are peering in on a sacred place for every engineer. Every code review is a final judgment on their life's work.
You're probably laughing to yourself, thinking: "Yeah, that function to send clients a reset password email is my life's work." I argue that it indeed is or for lack of a better phrase, a fraction of one's life's work. Code is a craft, and every engineer that gives a damn has put substantial effort into honing their craft and the way they write code. This is true even for junior developers that haven't spent much time in the wild of coding yet. They are still building on their legacy through code.
If you're a tech lead, senior, or engineering manager, your impact on others via code reviews is much more than you would initially think. If you are someone that another engineer looks up to, it's likely that the engineer trusts you and strives to learn from your behavior.
🎨 You Are A Painter
If you don't mind being a jerk in your code reviews, step back and imagine the following situation. You're now a painter. You are asked to paint a scene of an upcoming wedding. You are given a slight sense of style, effort, and medium, and you decide that you are up for the task, for the sum of $10,000. Sweet!
You go to the wedding and paint your heart out. It looks amazing, and more importantly, it looks like the scene of the wedding. You reveal it to the bride and groom, and all of their guests. The bride immediately starts shouting at you, "You missed the dog! You missed the sun's reflection on the tree! You need to add them!" [Missed requirements]
You're taken back, and much to your dismay you add the dog and the sun's reflection. You show your additions to the bride and groom, prompting the newly wedded husband to proclaim, "The dog doesn't look exactly like I would expect, don't you think dear?" The bride agrees, "Yes, something doesn't seem right, can you make it look more like the dog?" [Nitpicking]
Once again you change the painting, repainting the dog's likeness and revealing it to the couple. They ponder it for a bit, say nothing, and walk away to the next activity. [Review delay]
You are flabbergasted at their complete disrespect for your work, and there's a really bad taste in your mouth. You're worried that the display in front of all of their guests will ruin your chances of referral work. [PRs are in the open]
You're also worried that you may not get paid for the job, and that you're not that good of a painter. [Job security, imposter syndrome]
You go home, leaving the painting. Several days later you receive a call from the bride. "Listen, I'm sorry it didn't work out. We threw out the painting, but we'll still pay you for your time. Have a nice day." [PR ghosting, closing PRs]
This whole experience has changed the way you will approach jobs in the future, and now you're feeling like your effort doesn't matter all that much. Now, this is all a bit dramatic, but there are major similarities in coding and code reviews. I hope now you understand why you should invest in reading this guide.
🛑 It's Ok To Request Changes
Before we dive into the actual guide, I want to preface it with the fact that it's ok to request changes. It's also ok to nitpick, and request refactors of code. If there's a solid reason, or you're establishing standards, it's ok to demand changes.
📐 The Framework
I've followed this framework for many years and it has allowed me to tackle multitudes of PRs, including the bad ones. By following this framework, you're ensuring your reviews are consistent and deliver great results. After I go over the framework, I'll lay out 15 rules I live by during code reviews.