Category: Programming

Several months ago I heard or read about Code Reading Club for the first time. It might have been a tweet by Felienne Hermans, or it might have been in her excellent book The Programmer’s Brain, but I was intrigued. As a developer, I’ve often wondered what would be the best way to familiarise myself with a new codebase, or the best way to really understand what a specific piece of code does. Of course, I’ve learned several techniques over time, but the idea to deliberately practice reading code? Brilliant! So imagine my surprise when my friend Lisi Hocke reached out to ask me if I would be interested in joining her Code Reading Club. Well, yes!!

Online tooling

The club consists of several members in different countries and even different time zones and takes place online. We decided on a day and time that works for us, and use collaborative tools like Miro or Jamboard for our sessions.
This means everyone needs to make sure to have the code sample printed, or have a digital copy they can annotate with a digital tool. (And no, this is not supposed to be an IDE or editor with syntax highlighting, as part of the exercises is to look at the structure of the code.)

Exercises

All of our sessions so far have used the same exercises, using a different code sample (in a different language) each time. The exercises are taken from the starter kit.

The first session was very well prepared with a Miro board that contained everything we needed for the online session. The board contained the exercises, the code example and (where needed) space for us to place virtual post-its with our comments.

Introduction

We started our first session with a round of introductions, since not everyone in the group knew each other. We try to repeat that when new people join, as unfortunately not everyone is able to join every session.

Setting the scene

We start each session writing down what we are looking forward to or are excited about, as well as what we are worried or confused about. In the first session these comments were more about our expectations for the Code Reading Club in general.

For example, people mentioned they were excited about the following:

• Getting used to thinking through problems with unfamiliar tools & languages
• Understanding how others think about programming
• Taking advantage of our different experiences to learn more about code
• Looking forward to learning – both about code and about new people
• Some people also mentioned specific goals like getting better at code reviews, or improving their coding skills (from reading to writing).

In the next sessions the comments were sometimes more about how we were feeling (from being tired at the end of a long week, to being happy to see each other again) and about our progress in the club (for example, learning from each other, or fearful we’re not picking it up as quickly as we would like). What I love is that people feel safe in the group to share how they feel. And everyone is excited to learn with and from each other, and is supportive of each other.

First glance

The first exercise in code reading is called “First glance”. It literally asks to take a quick (1 minute) look at the code and note the first thing(s) you notice about it, and why. We’ve found that different people notice different things, for example things they are familiar with or confused about.
Some people focus on which language it is, or which programming constructs they recognise, while others focus on naming, whether or not there are comments or even import statements.

What’s also interesting is to talk about why these are the first things you noticed. Do you read the code from top to bottom like you would a piece of text in natural language (like this blog post), or do you scan the code and look at the blocks of code first, before looking at details? Do you focus on known or unknown concepts? All of these are opportunities to learn from each other and look at code differently next time.

Code structure

The next exercise is to examine the structure of the code, or rather its components or elements. We mark the variables, functions/methods, and object instances. It can be very interesting to identify these in a “foreign” programming language! We also draw connections between these elements in the code; for example, linking where a variable is used throughout the code, or a method call to a method.
This exercise is intended specifically to look at the structure of the code, and not its purpose. This turns out to be very hard, especially for people who really like to understand what’s going on! (Don’t worry, we’ll get there!)

Content

Next, we each identify the 5 most important lines of code. We notice that not everybody chooses the same lines, so we also discuss why people chose those lines in particular and learn from each other’s insights. For example, we don’t always have the same understanding of the meaning of “important”; does it mean important for the code to execute, or to understand what the code does? If the former, you might choose a main method as an important line of code. If the latter, you might choose a comment. Other people look at which lines are important for the control flow, or which lines are important to determine what to test (since some of the team members have a testing background).

Summary

The last exercise is to summarize the purpose of the code, or to describe what you think the code does to the best of your ability. It is interesting to see whether people have the same understanding of the code or not, but more interesting to see which information they use to get there. What strategies do they use to come to that particular understanding of the code? Which information in the code do they use? Or which knowledge of a particular language or concept? Often there is a lot of tacit knowledge involved. It can be really helpful to notice yourself making implicit assumptions and to make those explicit, not just for yourself but also for others to learn from.
This can also be a good time to explain where the code came from. It might help determine whether you think you’ve understood the code correctly. Although to me the point of the exercise is not to “get it right”, this can be hard for some people, so it can be helpful for the host of the session to provide some context.

Reflect

Finally, we reflect on the session and what we feel went well or could be improved for next time. One thing we noticed in the first few sessions was that we had to make sure we all had the code ready to annotate it (either printed or in some tool).
Some positive notes were on the structure of the sessions in getting to the meaning of the code, someone who had the opportunity to explain a programming concept or language feature to others, learning with and from each other. Someone commented that having context would help understand the code; they found not knowing frustrating. Someone else said “next time, can we read good code?” which was followed up by someone else who said that since reading an unfamiliar language is hard enough, we should have well structured examples. And while I understand those comments, the hard truth is that unfortunately we have to be able to read code that might be poorly written / structured, so in my opinion it’s good to practice that.

Conclusion

Overall, I really love our Code Reading Club. It is interesting to me to practice reading unfamiliar code and to deliberately practice that skill. But what’s even more interesting is to learn from everybody’s different perspectives, the different interpretations and conclusions based on different backgrounds and knowledge. What is clear or obvious to one person might not be to someone else. Hopefully that insight will translate into code we write in the future to make it clearer to others, as well as provide us with empathy and understanding for the writers of the code we read (in our club or at work). I’d highly recommend trying out a Code Reading session when you get a chance, or even to start your own Code Reading Club.