Humane Code Reviews - for Reviewers
Code reviews are one of the most fundamental quality control mechanisms in software engineering. They help us catch bugs early and maintain a consistent style and design across the code base.
Code reviews are also one of the most frequent forms of communication between software engineers. We might be interacting with a computer while creating and commenting on code reviews, but we need to remember that it is humans exchanging messages on either side. There are numerous anonymous posts on Reddit and Blind where software engineers share their dread of nasty code review comments. Code review etiquette can make or break team morale.
Both the author and the reviewer of a code review have their own share of responsibilities to make code reviews function well. In this article, let's focus on how reviewers can make code reviews a delightful experience for the authors:
Don't be a jerk: The author of the code review puts themselves in a vulnerable position by putting their work (or should I say, art) out there. Respect it, don't abuse it. Direct your feedback to the code, not the author. Disagree respectfully.
Delegate to tools: Use static code analysis tools and linters to identify code style issues, ideally as an automated build that runs when a code review is created. This allows you as a reviewer to focus on the more subjective aspects like readability, complexity and the intended functionality of the code.
Know your audience: The amount of detail you put on your comments should depend on who the author is. For example, if the author is new to the project, you might need to introduce them to dependent services before referencing them in your comments. If the author is new to a programming language, leave links to a style guide when asking them to use idiomatic syntax. If the author is a junior programmer, consider introducing them to engineering principles like DRY (when you ask them to avoid duplication) and YAGNI (when the code does more than it needs to at the moment). This will help reduce back-and-forth, and educate the author of new concepts. A win- win! On the flip side, avoid writing the code for them since it might come off as patronizing. Give the author the required amount of guidance, and let them do the coding.
Applaud good code: If you see good code, feel free to say so via your comments! There's no rule against appreciating a job well done in a code review.
Mark nits as nits: In general, avoid excessive commenting based on personal style preferences. But if you do add a comment that is minor, and wouldn't block your approval of the review, mark it as such. (And don't dwell on it if the author chooses to ignore a nitpick).
Make it a priority: Slow code reviews block authors from being productive, bring down the team's velocity and are a downer on team morale. Unless you're facing extenuating circumstances (e.g a pod issue), you should prioritize code reviews over other tasks on your list.
I will leave you with two excellent articles (1, 2) I came across during my time at Google regarding how to be respectful and civil while reviewing code. Can you think of any other ways to keep code reviews pleasant as a reviewer?