Few programmers think about it, but there is a strange gap in their professional education. Although most of their working time is spent reading code - they are trained predominantly to write it. There is little focus on active reading in software development culture.
In 2019 a group of programmers and scientists noticed this gap and created the Code Reading Club initiative. Since then, groups worldwide have been meeting online and offline to train the skill of reading code.
In this article, Rupert Redington, DataArt's Solutions Architect, explains how the club works, how you can benefit from conscious practice, and gives a tiny taste of the techniques involved.
What is it?
In essence a Code Reading Club is a bit like a book club, and a bit like an escape room.
A small group meet regularly to read and discuss short pieces of code. Each session is facilitated by a member of the group who has selected the code sample for the occasion and who guides the group through a series of exploratory exercises. Over time, the group improves its technique through practice and by experimenting with new approaches.
Code Reading Clubs have emerged in a wide range of environments, from introductory public sessions at conferences, through long-running groups in companies, to clubs focussed on specific codebases such as the Rust complier.
What is the experience like?
“I didn’t expect it to be so much like a detective story”
“It was cool how we worked together to figure things out. I learned so much”
Feedback from participants is very positive. People find sessions supportive and inclusive and are often surprised by how immersed they become and how rapidly the allotted time goes by.
Coming to terms with a short piece of unknown, decontextualized code, through a sequence of short exercises often gives rise to a game-like experience. Groups puzzle over unfamiliar syntax and patterns together, and try to deduce the sample’s function, and even the software if comes from.
At the end of the session the facilitator will usually reveal the project the sample was extracted from, with a little context, which tends to make for an exciting denouement.
To get a more detailed impression of how it feels look at Marit van Dijk’s excellent review of her experiences.
Try it! Three exercises to give you a taste of code reading practice
1. “First Glance” Exercise (3mins)
Most code reading club sessions will start with an exercise called “First Glance.”
Open the following code sample and glance at the code for no more than 30 seconds.
Then close that page and give yourself a minute to reflect. What was the first thing that caught your attention? And what was the second? Why do you think those things stood out for you, and can you make any connection between them?
In a club, we’d discuss each other’s impressions, reminding ourselves and each other to refrain from conjecture about what the code does at this point. We’re looking for insights such as:
- How do those initial observations help with deciding what to look at next?
- What lines or facts or concepts were chosen by everyone versus by only a few people?
- What knowledge surfaced in this process? Knowledge of the domain, of the programming language? Of a framework?
- What knowledge do you think might be needed to better understand this code?
2. “Structural Annotation” Exercise (10mins)
Structural Annotation is a pleasant visual exercise which tends engender a very meditative vibe in code reading club sessions.
Open the Code Sample and this time take your time. You can use the annotation tool to double click words in the code and give them colour, and then connect them with arrows. Once more, at this stage, try not to focus on the purpose of the code, or even its logic, but rather on its structure and flow.
You can use this tool (or pen and paper) however you like to explore the structure of the code, but often people choose to focus on the declaration and use of:
- Variables
- Functions / Methods
- Classes
- Dependencies
3. “Important Lines” Exercise (5mins)
In this exercise you’ll make your first approach to formulating your views about the purpose of the code. Using what you’ve understood during the two previous exercises try to select 3 to 5 lines which you think are the “most important” in the sample.
You can open the Code Sample again and use the coloured dots in the left margin to mark the lines which speak to you.
Of course, there is a lot to debate in this exercise... What constitutes a “line”? What does “important” really mean to us in this context? But those debates are best engaged in with friends. If they interest you, maybe you should look deeper into Code Reading Club!
Meanwhile, you’ll be curious about the code sample you’ve just been reading... Scroll to the bottom of the article for the spoilers.
What are the benefits of the practice?
- Experienced developers know that their work invariably involves reading more code than writing it, but little attention is paid to reading technique. By actively training these muscles we get immediate benefits when we:
- Work with legacy code
- Refactor for readability and maintainability
- Engage in code-review
- Scan examples and code-heavy documentation
- Code Reading Clubs encounter unfamiliar languages and patterns all the time. But they do so in a safe environment. This decreases fear of change and is a vector for the introduction of new ideas.
- Fledgling developers get valuable insights about how others leverage their experience to handle the unfamiliar. This accelerates learning appreciably.
- Folk from other disciplines such as Design and Product Management can participate. This removes some of the mystique around code and builds a team's ability to hold fluid inter-disciplinary conversations.
- Becoming a facilitator for a session is a comparatively low-risk way of building skills as a servant-leader. These skills help democratise agile ceremonies.
Where is the science?
Code Reading Club originates in the work of Dr Felienne Hermans, particularly her book “The Programmer’s Brain”. Her blog post from the early days of the clubs has a wealth of theory and plenty of interesting links to scholarly sources.
How do I get started?
The best way to experience a Code Reading Club is to get together with friends and colleagues and try a session or two. Facilitating your first session might seem intimidating, but this way your group will grow together and take ownership of the process.
You’re not alone though! The community at codereading.club have resources to guide you step-by-step through your first few sessions and a couple of tools to make online sessions more fluid.
There’s also a welcoming and gentle-paced Discord channel where you can get more advice.
Additionally, the codereading.club community run occasional public sessions online as well as at relevant conferences. They can also put you in touch with expert facilitators if you’d like help introducing Code Reading Clubs in a commercial setting.
So, if you find this practice useful and wish to enhance your code reading abilities, join the club!
SPOILER ALLERT! SPOILER ALLERT! SPOILER ALLERT! SPOILER ALLERT! SPOILER ALLERT!
It is from Microsoft’s VisualStudio Code, it is written in TypeScript, and it handles the colouring of matching bracket pairs in syntax-highlighted source-code. You can see it in context here: colorizedBracketPairsDecorationProvider.ts.
