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: 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. 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: 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?” 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: These outcomes all result in: 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 🌠.
How to Be Kind ¶
Why Be Kind? ¶
Posted
Posted