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