artisanal bytes

My father told me when I was a child that his father used to say, “Do as I say and not as I do.” My dad made sure to point out that that was a bad way to set an example, but what I’ve come to realize is that leading by example is not enough. If I had to craft a pithy saying it might be “Do as I do and as I say.”

Leading by example is not sufficient, for not all examples can be understood just through observation. Instead, you must explain what the example is and why it is worth following.

Take my friend who is relatively new to cycling. She has been commuting by bike for several years, but just this past year did she gain an interest in riding longer distances for recreation. I have been riding for considerably longer, so I try to set a good example. On a recent weekend ride, when we reached the top of our climb, I pedalled through, shifted up, and continued to pedal down the winding road, even though I was not picking up any speed from my pedalling. If my friend had been mimicking everything I did, she would have also continued pedalling over the crest and down the other side, but she would not have known why she was doing it. Instead, before we peaked, I should have explained that I was going to up shift and pedal to keep my leg muscles warm through the long descent. It was a particularly cold day, so any motion of the muscles was going to help stave off fatigue.

This same concept applies even more so to examples that cannot even be directly observed. When I bike past parked cars commuting through town, I often try to look in the side rear-view mirror to see if I can see a driver in the car. If there is a person, then I will swing out further away so I don’t get hit by the door. No one knows I am doing this, but if I want that example to be followed, I have to point it out. Furthermore, giving a reason for the action helps reinforce why it should be followed.

This principle applies just as well to work, too. One of the doctrines I advocate at work is “think before doing.” In the software world this typically means thinking about and writing down some sort of design before getting started writing code. Often times engineers want to just jump right into the coding part, because that is typically the most fun. But just a little bit of forethought can make quite a difference in the outcome of the project: both its quality and its timeliness. To reinforce my “think before doing” mantra, I make sure to write up wiki pages with design thoughts, rationale, arguments, and so on¹. If the content is appropriate, I will link to those pages in the code itself, or at least in tickets tracking the work. I don’t flaunt the process, but I very likely should. For engineers who I mentor, I encourage them to write up similar documentation and explain why it is useful. Sometimes they get it; sometimes they don’t.

One practice I have taken to recently is explaining myself in code reviews a whole lot more than I ever thought necessary. Instead of just making a comment about how a bit of code should be structured, I will give some reasons for why the new structure is an improvement. In a recent code review, I suggested using domain objects instead of nested generic data structures. In the past, I would have just left the comment, “Put this data in a POJO.” But this time, I explained that using a domain object will help make the data that is being stored more easily understood to future engineers who work on the code. It gives an opportunity for proper field names and comments to more clearly explain the purpose of the data.

I guess the next step is to explain why I added so much explanation to the comment: meta-leading by example.