Skip to main content

On Debugging

One of the stand-out collaborations of my career has been with my buddy Damien George. He's the creator of MicroPython ~ a lean and efficient implementation of the Python programming language optimised to run in constrained environments. When Damien created MicroPython I think he imagined "constrained environments" to mean microcontrollers - the small single chip computers beloved of embedded systems engineers, Internet of Things enthusiasts and the Maker community.

Little did he realise that MicroPython was an amazing fit for another computing context: the browser.

MicroPython

The browser is an interesting space in which to work because of its unique combinations of constraints.

Firstly, everything needed to view a web page needs to be delivered over the network. So, the smaller the asset to be delivered can be, the better. MicroPython, when compressed for delivery to the browser is only around 170k in size - smaller than most images you find on most websites.

Secondly, the browser is perhaps the world's most battle tested sand boxed computing environment. By this I mean that web browsers encounter all sorts of interesting, nefarious, ill-performing, badly written and otherwise shonky code. Such code should be constrained into a virtual sandbox, so it can't do any damage to the user's wider system. Because of the recent development of web assembly (shortened to WASM ~ a sort of virtual microprocessor working in the browser), code written in C can be compiled to run in the browser. MicroPython is written in C and Damien and his collaborators have worked together to create a port for web assembly.

Third and finally, the browser makes available to the developer of websites a JavaScript object called globalThis, through which all the other objects, functions and data structures needed to access the capabilities of the browser are made available. By constraining developers to a single means of interacting with the browser, there is only one way to go about making things happen. MicroPython compiled to WASM has access to the full capabilities of the sandboxed browser thanks to some of Damien's recent work on a foreign function interface (FFI) that interacts with the JavaScript based APIs and capabilities defined by globalThis.

Given this context, what does MicroPython allow you to do?

From within MicroPython running in the browser, one simply imports the js module (short for JavaScript). It's an object in MicroPython that acts as a proxy for globalThis in the browser. It makes interacting with the browser from MicroPython an absolute joy. It's worth pointing out that Damien's work is based upon the js work done as part of the Pyodide project (a version of the CPython interpreter for the browser), so no matter the version of Python you use in the browser, you access the browser's capabilities in exactly the same way.

But recently, there was a problem.

I was due to give a talk about PyScript (a platform for taking MicroPython and Pyodide and making them easy to use in the browser) at EuroPython and I was putting together code examples of ever increasing complexity to present as part of my talk. But I kept hitting strange errors when using MicroPython. My colleague and web-guru Andrea managed to isolate the problem but had been unable to work out why it was happening. Put simply, somewhere in MicroPython's FFI, at that point where JavaScript and MicroPython were interacting, unwanted JavaScript objects were unexpectedly leaking into the MicroPython world thus causing things to crash. Think of it as a JavaScript shaped spanner in the MicroPython works.

This wasn't a good situation to find oneself in, a few days before presenting at one of the Python world's largest and most prestigious conferences.

Damien and I decided to debug the problem, and we recorded ourselves doing so because Andrea wasn't available at the time of our call. We figured that if he could watch our debugging session, he might spot something we hadn't and suggest a fix.

In any case, what followed was a lot of fun, and the video of the debugging session is embedded below.

There are some things you need to know before you watch the video:

  • Both Damien and I know JavaScript to a sufficient level to be "dangerous". We can get stuff done, but we're not guru level like Andrea.
  • Damien is an expert in C (the language used to implement MicroPython) and clearly knows his way around the MicroPython codebase including the FFI that kept crashing. I am familiar enough with C to be able to read it, but not very experienced at writing it, and I certainly don't know anything about the MicroPython internals, including the FFI.
  • We were using a collaboration technique called pair programming: where one developer (Damien) is the "pilot" with the other developer (me) acting as "co-pilot". As you'll see in the video, Damien was sharing his screen so I could see what he was looking at and he'd often describe things, processes or problems to me, only for me to confirm them, explain them back or ask questions as a way to help maintain focus. As the one most ignorant of the language and code-base, I was in a good position to play the beginner to Damien's expert, and ask for clarifications.
  • Our debugging involved taking very careful steps to investigate and change the code so the problem was (happily) eventually revealed, tested and fixed. As the Chinese proverb explains: when crossing a river, it's best to do so slowly and by feeling with one's toes.
  • Both of us were having a lot of fun in different ways. Damien was clearly fascinated by delving into the problem. I was enjoying Damien's virtuosic debugging performance, and found out some fun stuff as we went along.

So grab your popcorn, and enjoy the show:

Rejection and Renewal

In June I was contacted by a friend in the EuroPython community.

They were looking for articles about how to deal with rejection and what to do when one's proposal for a conference talk wasn't accepted. Since they couldn't find anything suitable, they asked ChatGPT for suggestions, and this is how it responded:

In an entirely predictable turn of events, ChatGPT was wrong (no such post existed at that time), and so I puckishly proposed writing such a post. We can't have ChatGPT telling lies can we?

This is it.


It is a rare privilege to find oneself in a community who genuinely cherish and support the participation of all. Such company guarantees we encounter folk who are different to ourselves: an opportunity to learn from each other's contrasting backgrounds, experiences and perspectives. It's why diversity is a precondition for growth: our worlds are mutually enlarged by our differences.

But this isn't an easy journey.

It takes compassion, empathy and thoughtfulness to nurture a safe space where such encounters take place. Participants - through their actions, attitudes and attention - embody and live the inclusive and open minded ethos necessary for such a precious situation. This is a complex relationship between the individual participant's personal outlook and the collective esprit de corps that emerges from the aggregate contributions and interactions of many different individuals.

Here's the challenge: it's not enough for a group to say they're inclusive, open-minded and whatnot... that's just empty virtue signalling. Merely "going through the motions" is an ignorant and insidious sort of cultural cargo cult ~ communication at the expense of community. It happens far too often, and normalizing such behaviour actively diminishes the possibility of a genuinely inclusive and open-minded space.

Rather, such a community spirit springs from the quality of the interactions between individual participants. Sometimes such interactions are unavoidably painful: as when a proposed contribution to a community event is rejected by the organisers.

Yet it is at these moments when embodiment by individuals, and the emergent community spirit, are so important.

This equally applies both to organisers and participants.

If you are an organiser of a community event, and have a call for proposals but limited space, then you will inevitably reject (and therefore exclude) some of the proposed contributions. If you believe in a diverse and inclusive culture then this process may feel deeply uncomfortable and paradoxical.

But this is the puzzle you face, and (I'm sorry to say) there's no right answer.

Actually, the notion that there is an answer to such a situation is, I believe, deeply flawed. Rather, how you choose to conduct yourself, pay attention to the situation and engage with the unfolding events will reveal your community's spirit. I hope you make a conscious personal decision to choose compassion, empathy and thoughtfulness over going through the motions of a performative brain dead cultural cargo cult.

Alternatively for participants, it can be deeply upsetting if your contribution to an event has been rejected. All sorts of complicated feelings may come up (although some may just shrug and move on). I want to reassure you that it is natural and understandable to feel sad, disappointed or upset by such rejection. Lean into such feelings and give them the time and space they deserve. The worst thing you can do is ignore them.

Most importantly, pay attention to what happens next.

If the organisers of the event embody an inclusive and empowering community spirit, their interactions with you will be affirmative, compassionate and supportive. If you engage in good faith, such organisers will likely welcome feedback or suggestions. But please remember they're human beings too and they may respectfully disagree with you. This is what it is to be in a diverse community - you'll meet folk with different outlooks to your own.

It's an opportunity to learn!

As an exercise in self-understanding and growth, you may want to explore why your proposal was rejected (if this hasn't already been explained). Such feedback is best received in a spirit of constructive collaboration. You'll either discover how to improve your next proposal or come to see how the event in question isn't a good fit for what you want to contribute.

If the former, reflect and refine for next time.

If the latter, your niche might be elsewhere, so keep exploring!

If the event organisers are simply going through the motions, you'll know to avoid the event in future.

In any case, be you an organiser of or participant in community events, best of luck. Just remember flouishing and fulfilling communities are all about the quality of individual interactions, something over which you have direct control: how you choose to participate.

Peace.

8-Bit Archaeology: Part 1

This is the first in a semi-regular series of posts about digital archaeology relating to 1980s era 8-bit microcomputers. In a strange turn of events, not only am I the archaeologist, but it is my own code that is to be uncovered and interpreted.


The aim was to democratise computing. We didn’t want people to be controlled by it, but to control it.

~ David Allen, Project Editor, BBC Computer Literacy Project.

As a child, the first programming language I learned was Sophie Wilson's BBC Basic, written for Acorn's BBC Micro. Without this formative experience, I wouldn't have become a professional software engineer.

Most of my childhood was spent in the 1980s, and in 1982-ish the UK Government ensured every school in the UK had a BBC micro.

A BBC micro from the 1980s
A BBC Micro from the 1980s. Source: StuartBrady, Public domain, via Wikimedia Commons.

My father was headteacher of a school, and so brought his newly arrived computer back home one holiday to figure out how to use it. It didn't take very long to prize the device away from him, and so I started to explore the "Welcome" software, loaded from a tape via a sequence of squeaks and growls (representing the bytes to load into the computer's memory). Since I would have only been eight at the time the user guide was beyond my understanding, so a trip to the local library furnished me with a new book aimed at kids who wanted to play games on their computers. The book in question was Computer Spacegames published by Usborne, a title in their famously brilliant series of colourful and engaging books about coding.

The first proper program I ever typed into the BBC can be found on page 5. It's a sort of text based rocket pilot game... you have to take off before the aliens get you:

10 CLS
20 PRINT "STARSHIP TAKE-OFF"
30 LET G=INT(RND(1)*20)
40 LET W=INT(RND(1)*40)
50 LET R=G*W
60 PRINT "GRAVITY= "; G
70 PRINT "TYPE IN FORCE"
80 FOR C=1 TO 10
90 INPUT F
100 IF F>R THEN PRINT "TOO HIGH";
110 IF F<R THEN PRINT "TOO LOW";
120 IF F=R THEN GOTO 190
130 IF C<>10 THEN PRINT ", TRY AGAIN"
140 NEXT C
150 PRINT
160 PRINT "YOU FAILED -"
170 PRINT "THE ALIENS GOT YOU"
180 STOP
190 PRINT "GOOD TAKE OFF"

I have a vivid memory of my aunt, uncle and cousins visiting at the time. My cousin Michael (five years older than me) shared a fascination with computers. As a teenager he was clearly at a more advanced level of understanding, and it was from him that I got lots of tips, tricks and encouragement to goof around.

So I did.

I changed line 160 to read:

160 PRINT "YOU ARE AN IDIOT"

Then I persuaded my unsuspecting Uncle Colin to play.

Since he's an engineer I think he got the impression there was some sort of simulated Newtonian mechanics going on and took it quite seriously. Of course, if you read the code, it's just a glorified guessing game. When he inevitably failed to take off, I remember he exclaimed "how rude", muttered something about the computer being broken then wandered off to escape any further computer-related space piloting catastrophes. But my eight-year-old self was delighted. I spent the next ten minutes laughing like a maniac at having hoodwinked an adult with my modified code.

Emboldened by this turn of events (and Michael's mischievous teenager-y encouragement) I soon graduated to a new form of entertainment when dragged shopping by my parents. I'd wander off on my own to find the computer stands in retailers. Being a kid, I was mostly ignored as I typed code into the demonstration machines.

Code like this:

10 CLS
20 PRINT "YOU ARE AN IDIOT"
30 GOTO 20

I'd walk away (after typing RUN) and surreptitiously observe the next person to encounter the demonstration machines... all telling them they were an idiot ad infinitum. I soon realised the shop assistants could clear my school-boy silliness by pressing the ESCAPE or BREAK keys. Yet I also realised it was possible for the function of such keys to be modified: some of the code ran on my school's BBC micro clearly made sure any accidental or deliberate use of ESCAPE or BREAK didn't interfere with whatever software the teacher had set up for us to use.

I had to wait for the next visit of my cousin Michael to learn how to "improve" my code so it defeated shop assistants. To cut a long story short it's possible to rebind the ESCAPE and BREAK keys to the extent that the only way to stop the machine from doing what it's doing is to switch it off and on again. My cousin pointed out that the answers to such problems could be found in the (afore linked) user guide. In fact rebinding BREAK was explained on page 143 and disabling ESCAPE involved this magic incantation at the start of your source code:

10 *FX 200,3

I was off!

Most importantly, I realised the user guide wasn't a boring manual for adults but, if approached in the right way, it was the source of all sorts of useful knowledge and information and I merely had to figure out how to find it. I was also helped by yet-more-computer-books from Usborne and my local library, a subscription to Acorn User Magazine and various aspects of the BBC's magnificent Computer Literacy Project, including TV programmes like this one:

You can watch all the original 146 programmes online.

But in the end I learned an important ethical lesson.

After leaving my unstoppable and mildly insulting code running on a BBC micro at the Mansfield branch of WHSmith, I was horrified to see one of the retail assistants reprimanded by their supervisor. My joke wasn't funny and I realised my code had consequences for others. A lesson that stays with me to this day.

I also learned that revealing technical skill and knowledge can be tricky and, at times, intimidating to others.

I remember getting a severe telling-off after I tried to help one of my parent's teaching colleagues, the subject matter specialist for computing. I was still at Primary school (probably around ten years old) and the ensuing conversation, in front of my class mates, revealed the teacher's ignorance of some aspect of how the BBC micro created sounds.

The conversation went something like this:

TEACHER: "You can only make sounds like this."
ME: "But Mrs.S, it's easier to make sounds like that."
TEACHER: "You're wrong Nicholas. That simply won't work."
ME: "Oh yes it will."
(I demonstrate the damn thing working.)

In my enthusiasm to share a cool hack, I undermined the teacher and paid the price with a bollocking.

To be clear, I wasn't rude. But I was certainly a confident enough ten-year-old to know I had an easier way to make things work, while being naive to think this would be welcomed. To be fair, I don't think they did themselves any favours by telling me it simply wouldn't work. A more open minded teacher would have said something like, "OK Nicholas, show me your way and let's compare notes", and used the situation as an opportunity for learning. Yet, as a former teacher myself, I know that it's often impossible to go off piste in a tightly structured or time constrained lesson.

Such reminiscences are a prelude to the real digital archaeology.

Last year I found my old BBC micro, and a box full of floppy disks, in my parent's loft. With their permission I took my finds to the UK's National Museum of Computing (based at Bletchley Park ~ a mere 15 minute drive from where I live). I'll describe the details in a follow-up post, but with the generous help of others, I was able to extract the content of the disks.

By way of preview, this link takes you to an online BBC emulator running a sort of "greatest hits" compilation of programmed musical performances.

I put together the disk from various sources floating around my friendship group, and included some of my own code too. The disk's menu system is of my own creation but based upon two other fragments of code I found in a magazine: one for driving a disk menu, the other for using arrow keys for selecting items. I'm also responsible for the rather awful renditions of "The Swan" and "The Road Goes Ever On" (a musical setting of some of J.R.R.Tolkien's poetry from the Lord of the Rings, by Donald Swann). If I remember correctly, I was thirteen years old (in year 9, 1987) when I put this disk together. As we'll see in future posts, it was a significant year for me in terms of coding and music.

Use the up and down arrows on your keyboard to navigate the menu. Keys like RETURN (to make a selection) and ESCAPE (to stop a piece and return to the menu) will behave as usual. However, I'm sorry to report I used the *FX 200,3 trick with "The Swan" ~ you're just going to have to sit through that monstrosity in its entirety without the use of the ESCAPE key.

"You're welcome", says my thirteen year old self. ;-)

This is but a small example of some of the fascinating things I've found.

In future posts I'll reveal more about my programming, dive a little into the technology I was using and try to place it all into the context of my life at the time. As some of you already know, I'm actually a classically trained musician, and this has some bearing on what I've managed to find... or more accurately, what I've managed to find has some bearing on why I'm a classically trained musician, who works as a software engineer with a passion for computing education.

Finally, it turns out that the BBC micro didn't create a legacy of fond memories and technical skill just for me. There are many folks of my age who have similar stories to tell.

Happy new year! More soon...

PyCon Ghana 2022

It was an extraordinary privilege to be one of the keynote speakers at this year's PyCon Ghana. I was also very lucky to have the support of my employer (Anaconda) who covered the costs associated with the trip for myself and my colleague, Cheuk.

While this was my first trip to Ghana (actually, it was my first trip to Africa), this was not my first Ghanaian interaction.

I can't begin to describe how important and nourishing the stimulating interactions I've had with Ghana based friends Mannie and Michael have been. Two years ago we were introduced by our mutual friend Conrad Ho, and since then have met every month, in video calls, to discuss Python in education. The work done by the Ghanaian Python community to engage in educational activities is truly inspiring, and you can find out more here.

That both Mannie and Michael are part of the PyCon Ghana organising team, and this year's focus was on Python in education give a clue as to how I got invited.

A view from our accommodation
The view of Accra from our accommodation.

After an eventful flight to Accra, both Cheuk and I went exploring during our first full day. Adjacent to our accommodation was Oxford Street, containing lots of shops, banks and other useful things we needed to visit. My immediate impression was very positive... the Ghanaian folk we met were all friendly and welcoming. "Good morning", "Hello", "Welcome to Ghana" and other such greetings were common as we walked through the streets.

We also met the PyCon Ghana organisers at the venue. Having been involved with community organising for well over a decade, I looked on in sympathy and (where possible) got stuck in trying to help get everything set up. Like most aspects of the Python community, PyCon Ghana is run by volunteers, and I'd like to acknowledge their strength of character, friendliness and can-do attitude, led by their chair, Francis. I saw first hand, that the Ghanaian Python community is in good hands.

Sadly, I was ill on Thursday's tutorial day. My son had shared his cold with me and it meant I had to stay home instead of attend Cheuk's amazing humble data workshop. But the enforced day of rest meant I was ready for Friday and Saturday at the conference.

I was honoured to meet Nii Quaynor a Ghanaian gentleman who is often described as the father of the African internet and an inductee to the Internet Hall of Fame. Nii eloquently spoke with considerable experience and authority of the challenges and opportunities for working with governmental and international agencies. I hope folks were paying attention since the Python community in Ghana could be a significant contributor and collaborator in the technical growth of the country.

There were also many other interesting talks, panels and workshops happening at the event which made it feel like a typical Python conference found anywhere in the world.

My first proper contribution to the conference was to run a two day workshop on MicroPython on the micro:bit for young people. I have to say this was an absolute joy and, assisted by Anthony and Joanna, we were also joined by a collection of teachers, tech folk and IoT curious. The vibe was friendly and the young people brought lots of energy and enthusiasm.

Here's a video, shot on the second day while folks were building a project with their micro:bit, to give a flavour of what went on.

Many thanks to the MicroBit Foundation for supporting PyCon Ghana via the donation of 20 devices for participants to use and then keep. Every device found a safe home, with many asking where they can be obtained in Ghana..!

My keynote, on the subject of Python in Education, went well and as usual, I especially enjoyed answering the questions at the end.

I was especially pleased to channel my "inner teacher" by (half jokingly) setting the conference some homework.

I pointed out that somewhere will become known as a place of African technical innovation. Somewhere will be lauded as having the most accessible and creative coding education programme in Africa. Somewhere will famously contribute a uniquely African story to our global technical community.

I asked, "why not you..?".

My homework task to the audience was to discover and become their own unique, colourful and extraordinary community. They already have a small but strong, vibrant and close knit nucleus from which to grow.

I hope, in ten years time, to visit Ghana again and have some of today's community say to me, "see what we did, and look where we're going...", and for me to be amazed.

Ghanaian friends.
Ghanaian friends.

Another aspect of the conference was its friendliness.

During the breaks I spoke to many different people, from all over Africa, and drew energy from their passion, enthusiasm and openness.

I also enjoyed the warmth of their conversation and willingness to share games with me... I especially appreciated learning how to play Oware from PyCon Ghana organiser, Hillary. I enjoyed it so much I managed to buy a board in a market in Accra and have taught my kids and wife how to play..! It's a big hit in our house.

The amazing view of a beach from the old presidential residence.
The amazing view of a beach from the old presidential residence.

On my final day, the day after the conference, we hung out with the conference organisers and visited tourist sites in Accra. It was wonderful to see non-Pythonic aspects of Ghana... its cultural spaces, historic monuments, the university and glimpse some of its natural beauty.

Through the course of my stay, I saw the twi word "akwaaba" in many places.

When I asked what it meant I was told it was a sort of very hospitable form of "welcome".

"Akwaaba" is a pretty good word to describe my experience of PyCon Ghana.

Long may the Ghanaian Python community flourish and I look forward to 2032. ;-)

Great Code Reviews

As I've mentioned elsewhere, I've just started a new role at Anaconda.

A week after joining I was asked to contribute an article to an internal newsletter called "Consider This!". The format is simple: write something thoughtful on a subject of interest to folks within the company, and, at the end, curate a list of questions to prompt further thought and reflection.

I was invited to explore what I considered important aspects of great code reviews. Thanks to Anaconda, the article is reproduced below. Additional thanks to my colleagues Elise and Dan who provided invaluable and stimulating feedback to significantly improve my first draft.


Ask a room of engineers what makes a great code review, and you’ll have as many different opinions as there are engineers. Yet, in my experience, common themes and archetypes emerge from the gloriously colourful and diverse descriptions of a great code review. This article aims to explore what they might be.

At its core, a code review is exactly what it says: asking another to review code.

Why might one do this? Often the simple answer is, “because I have to”.

Code hosting sites, like GitHub, make it easy for code reviews to be part of the development process through concepts like pull requests (PRs for short). Simply make a change to the code, bundle your changes into a PR, submit it and wait for feedback from maintainers or colleagues. Sometimes you have to submit code for review because of corporate governance, your employer or the open source project to which you’re contributing may have an existing review process for all contributions. Or it may simply be habit or herd instinct to follow so-called “best practices”... folks do code reviews because everyone else does code reviews and so they’re living up to expectations.

A code review could be an assessment to overcome, where someone in authority accepts or rejects your changes. It might involve checking your changes to ensure you’ve followed stylistic and technical conventions for a project, like a teacher correcting work with a red pen. Furthermore, opinions about the approach taken, methodology used or even the intention behind the change might be offered, like a critic describing a restaurant, film or concert.

But there’s another, more engaging reason to participate in code reviews: if done well, your world as a coder is enlarged by the process, be that as a reviewer or contributor. In so doing, engagement with the project is a process of growth, and the quality of the codebase is improved to reflect the shared goals, ideas and aesthetic of those bringing the project into the world.

If a code review is used as a means of exercising authority then it’s no better than pandering to another’s ego. Many projects have stylistic and technical conventions, and checking such things can be easily automated so contributors are confident their changes meet such minimum requirements before ever submitting their code for review. Finally, if a critique of the approach, methodology or intent is offered as part of a code review, then it’s happening too late; such things should be discussed before code is submitted for inclusion in the project, perhaps in early drafts (so called “code spikes”) or exploratory proofs-of-concept.

From the contributor’s point of view, a code review is an opportunity to share their work so others understand and see what they are offering. In other words, a code review is an exercise in education as others encounter and explore new aspects of the code base. From a reviewer’s point of view, a code review is an opportunity to explore, internalise and offer constructive feedback of another’s contribution. Once again, it’s an exercise in education as the contributor is invited to explore their own work through the fresh eyes and constructive commentary of the reviewer.

Earlier, I deliberately used the word “enlarge” when I said a code review enlarges the world of those who participate. Enlargement is not synonymous with “fun”, “positive” or “easy”. The process of enlarging one’s view of the code might feel uncomfortable (perhaps you’re trying to get your head around a difficult or unfamiliar concept), negative (you feel frustrated with yet another bug in a hard-to-fathom part of the project) or difficult (the task at hand is complex and requires much effort simply to engage effectively).

Yet, enlargement implies growth, understanding and progress, and I’m reminded of the types of fun mountaineers use to categorise climbs.

A climb that is type one fun is fun because it’s fun to do, type two fun is not fun at the time but fun to recollect afterwards because of the achievement gained or lesson learned, and type three fun is not fun at the time, nor fun to recollect because you realise you never want to be in that situation ever again. Given a receptive spirit of learning, a mountaineer’s view of the world is enlarged through a mixture of both positive and affirmative, as well as negative and difficult, experiences.

So, how do we foster a spirit of enlargement in code reviews?

I believe mutual respect is key. Respect involves showing empathy, gratitude and acknowledgement that, when difficulties arise, folks involved are acting with the best of intentions. Another key factor is trust, an attribute of a team that only comes through working together over time, making mistakes together, and seeing evidence that folks support each other. I’d add that compassion (an awareness of and sympathy for another’s feelings and situation, mixed with a proactive desire to engage) is a great way to show support. When things inevitably become difficult, then compassion for each other is a way to embody mutual respect and build trust.

In the context of code reviews, such attributes help our judgement to become deeper, more refined and aware of the wider context of the project and its participants. A code review is no longer just an arbitrary measurement of “quality” (have you followed our code conventions?), but becomes an exercise in mutual learning and improvement that encompasses both enjoyable and challenging aspects of participating in a coding project. At the heart of this process is a strangely humorous paradox, as demonstrated by this old joke:

STUDENT: O Guru, what is the secret of success?
GURU: Good judgement.
STUDENT: How do you get good judgement?
GURU: Experience.
STUDENT: How do you get experience?
GURU: Bad judgement!

Only when folks feel safe to exercise potentially bad judgement (through the code they offer or the feedback they give), will they be able to gain experience and learn good judgement. The code review is a place to pay attention to each other’s contributions to facilitate mutual learning and growth. This will, ultimately, improve the project as a whole, and help its participants better engage with the tasks at hand.

“But”, I hear you ask, “what things should one do in a code review?”

If you’re expecting a “top ten interventions to make in a code review” type post, you’re in the wrong place. In fact, such naive shopping lists demonstrate a rather transactional and limited view of the process of a code review, while completely missing the point I’m trying to make. I hope you focus on embodying and passing on the sort of attributes that make a project an enlarging place in which to contribute: mutual respect, trust and compassion.

Perhaps we could learn by examining what other disciplines do when something is offered and feedback is given. For example, such a process is at the heart of musicians rehearsing (no matter the genre of music).

This short fragment shows Leonard Bernstein rehearsing an orchestra. Clearly the triangle players are not playing to the high standard he expects.

I want to draw your attention to the relationship between the musicians involved. How do Bernstein and the percussionists appear to you?

Folks might think Bernstein is condescending, sarcastic and not particularly supportive. Others might see him as setting clear (and very high) expectations through humour. Others might focus on Bernstein’s clear ignorance of triangle playing and the resulting laughter from the percussionists. That we see the same thing in different ways is itself an interesting and important outcome of our diverse and multifaceted backgrounds (and it’s important to acknowledge and recognise such differences).

The important relationship, upon which I want us to focus, is that between Bernstein and the musicians. Only when there's mutual respect, a feeling of safety and trust can such potentially difficult conversations, involving the giving and receiving of constructive criticism to fulfil some important end, take place. How such discussions unfold will reflect the unique relationship cultivated between the participants. So long as both parties share a bond of trust and respect, and we recognise and respect such a bond reflects their unique relationship with each other, then we can engage with and learn from the feedback and what the outcome tells us about the endeavour. In other words, our world is enlarged by observing their interactions.

Questions to Explore:

  • How has your world been enlarged through a recent code review?
  • Remember a time when you received valuable feedback or an important lesson that enlarged your world; how was it revealed to you?
  • What is your team’s approach to code reviews?
  • How do you and your collaborators cultivate a place of mutual respect, trust, and compassion?
  • Put yourself in Bernstein’s shoes, what would you say to the percussionists?
  • Imagine you’re the percussionists, how would you respond to Bernstein’s feedback?
  • Think of a recent PR submitted for you to review. How did you help enlarge the world of the author? How was your world enlarged?