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.
TIL how to tie my shoes 😐.
I figured this out today – the last day of 2019 – while I was tying together two ends of cotton sash cord to make a loop. I suddenly noticed my square knot didn’t look like the cover of the Boy Scouts knot book.
I looked up the square knot on animatedknots.com – which is an amazing site with step-by-step instructions for all kinds of knots. Sure enough, I had been doing wrong – left-over-right, left-over-right – a granny knot vs a square knot.
This was satisfying, if a little embarassing – I somehow made it through Cub Scouts without learning to tie a square knot. As I kept reading animatedknots.com I learned something else:
The Square (Reef) Knot […] is usually learned when we tie the laces on our first pair of shoes. Admittedly it is usually a bow that we tie – but the underlying knot is a Square (Reef) Knot.
I quickly untied and retied my shoes – left-over-right, left-over-right – damnit – a granny knot. It’s especially frustrating given that I’d seen Ian’s Shoelace Site’s page on Granny Knots forever ago and dismissed it because my shoelace bows weren’t askew.
So here I am – a living cautionary tale. It’s the last day of 2019. I’m 33. And I just learned to tie my shoes 🌠.