We have a “book” club at work. I say “book” because it’s more of a media club – we discuss books, articles, videos – anything that’s topic is related to engineering productivity. We recently read Google’s Engineering Practices doc How to do a code review.
The guiding principles of this document were excellent:
- Default to merging code
- Don’t merge anything that doesn’t improve code health
- Focus on speed and time to first comment
One part of this document I’ve been ruminating on is the first summary item for how to give comments – Be Kind.
There weren’t many instructions for how to be kind, and there was no discussion about why it’s important to be kind.
How to Be Kind ¶
Being kind is not seen as very expedient. In code review, we’re told, speed is important. A kind code review can be an expedient code review by following simple heuristics, the first of which is listed in Google’s code review guidelines as a means of courteous review, “Make comments about code and not about the developer”. I think a few additional heuristics may give a fuller list:
- Assume good faith
- Make comments about code and not about the developer
- Never use the words “obviously” or “clearly” – if it were obvious or clear it wouldn’t need to be said
- Be explicit and assume a low-context culture
This final point requires some unpacking. Much time is lost by contributors meditating on comments of reviewers – be kind to contributors – tell them what you mean as clearly as you can.
In the Google code review guidelines they say, “If you ask a developer to explain a piece of code that you don’t understand, that should usually result in them rewriting the code more clearly.” This is an example of a code review expectation in a high-context culture like Google – it’s implicitly understood that asking for clarification means a rewrite or a comment – your code is unclear!
At my work, I may receive changelists from folks with whom I share very little context. Rather than use a less-direct message that may have more meaning to me I can be more explicit and say, “This function doesn’t make sense to me, could you rework it a bit to clarify its function?”
Why Be Kind? ¶
Being kind in code review directly affects the health of your project.
There’s a imbalanced power dynamic in code review between reviewer and developer. This imbalance of power is by design – one of the functions of code review is to serve as a pedagogical tool – bringing developers up-to-speed on a project’s standards quickly. Power imbalances in code review, if unchecked and persistent:
- Demotivate existing contributors
- Repel new contributions
- Have a chilling effect on contributions in review
These outcomes all result in:
- Fewer new contributors
- Fewer contributions from existing contributors
- A lower diversity of contributors
- An overall slower pace of change
One point in Google’s documentation that bears repeating, “there is no such thing as perfect code, only better code”. Improving code is an iterative process; the fewer contributors and the few the iterations, the fewer and slower the improvements. In short, persistently uncivil code review is an existential threat to a project.