"Code Review" is a term that often summons a feeling of dread in developers. Long, arduous, and confusing code reviews have become standard. "Bikeshedding" is a competitive sport. Jira tickets hover in the "review" lane for days while project managers inquire about ways they can help "get the ball rolling" (if you'd like to facilitate this debate thread about the readability of line 242 in NewFile.ts, be my guest).
In addition to blocking release cycles, code review can prime one's system for scheduled anxiety attacks. Feedback is important for growth, but we are all human (for now), and it can be difficult to separate creation from creator when receiving criticism. Code is essentially an extension of the writer's brain, and there are ways to critique it without jeopardizing the mental health of the author.
In my eternal pilgrimage to de-cringify code review, I employ these foundational principles.
Pre-work: Establish reasonable and firm code style standards
One of the primary culprits for an exasperating code review is the lack of a "source of truth" for important code style standards. Reviewers are forced to labor over small, but important offenses that would have never seen the light if core principles were enforced with documentation and automated linting pipelines. As a bonus, this precedent will also help new engineers quickly onboard and adapt to your team's coding style.
1. Explain the "why" behind your change requests.
Few things are more harmful to a budding engineer than change requests with no explanation. Provide documentation and links to resources that explain your points if they are available. Your explanation does not need to rival the length of a novella, but it should provide the author with a foundation to understand your perspective and conduct their own research on the matter. This helps cut down on repeat offenses. It encourages the author to take the time to learn something new, rather than push up poorly understood changes for the sake of a quick merge.
2. Make your intent clear
It can be difficult to determine tone and intent in review comments. Does the comment denote a required change? Is it merely an observation, or personal opinion? Much time can be wasted on deciphering tone and following up with additional questions. An excellent, concise way to combat this ambiguity is to utilize a documented "emoji code" when leaving review comments.
Example:
👍 : Great work! (Positive reinforcement of things that the author should continue doing)
🔧 : This is a strong recommendation rooted in good practice and intention, but not a change requirement.
❗: This must change. Reserved for more serious offenses that would cause harm to the product or codebase.
💭 : This is an observation. I have thoughts, but no firm solution. (Great for encouraging discussion)
🙃 : Nitpick. A personal opinion on how something should be, but not a requirement or anything serious. (Use this sparingly).
3. Whenever possible, avoid nitpicking.
Nitpicking tends to take the passenger seat at code review when it barely deserves a pull out seat in the back. Newer developers tend to nitpick the most often - as it's easier to point out small "potential flaws" in code style than hone in on serious or complex architecture and performance issues.
Comments such as "You should use an implicit return here, it's shorter" are personal opinion, and a waste of effort for the author to digest, fix and await re-review. If your small grievance isn't in your team's style guide - ask yourself if it's important enough to become an addition. If it's not, your opinion will likely be better kept out of a code review.
4. Provide positive reinforcement often
Code reviews are primarily filled with acknowledgement of mistakes, and seldom filled with recognition for work done well. Imposter syndrome is a vicious beast that runs rampant in developers of any level, and I theorize that this is partly because praise is considered a precious resource to be hoarded rather than freely given. If you like the way that a developer solved a problem, say so! If you find a line of code beautiful, sing its praises. Thank your peers when they teach you something new.
As a younger, anxious developer in an underrepresented demographic, I grew the most when I joined a team that valued positive reinforcement. I began to feel comfortable sharing knowledge, writing documentation, and mentoring other engineers when I was finally given feedback that I was good at my job, and not on the verge of being fired like I so often assumed due to past environments avoiding praise.
5. Encourage discussion
When requesting changes, ensure that you keep the floor open for discussion and debate. Asking questions such as "What do you think of this?" when proposing alternative solutions can help the author feel comfortable voicing their concerns if they disagree or have other possibilities in mind. We all wield unique backgrounds and perspectives, and can learn from each other regardless of level or tenure.
6. Practice Empathy
Finally, it's important to incorporate empathy when reviewing code. Humans are creatures of soul and emotion. While it's important to ensure that code is up to snuff, it's also important to put ourselves in the author's shoes. Offer to pair with new developers on problems that are difficult to grasp when presenting change requests. Remember to provide positive reinforcement. Ensure a kind, professional tone when leaving comments - it goes a long way!