Code Reading Club

Facilitators: Katja & Rupert

hello@code-reading.org | https://code-reading.org

• Code of conduct
• Miro board
• Code in annotation tool

• Grab a copy of the code
• I'll keep the exercises & timer posted on my screenshare
• Join the miro and claim a board
• Make independent notes on your board
• After each exercise we'll copy any thoughts we want to share to a shared board

First glance

The goal of this exercise is to practice to get a first impression of code and act upon that. We all have different instincts and strategies for where to start when faced with a new piece of code. It doesn't matter how trivial you think the first and second things you noticed are.

Glance at the codeIndependently1 minute

It's important that what you use is your immediate reaction, don't overthink it!

• Look at code for a few seconds. Note the first thing that catches your eye
• Then look again for a few more seconds. Note the second thing that catches your eye
• Now think about why you noticed those things first & note that down

First glance

DiscussTogether8 minutes

Talk about why things might have jumped out for different people. It might be tempting for some people to start talking about the big picture; try to steer discussion back to individual details, rather than summaries.

• 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?

Reflect also on what kind of knowledge you used in this exercise.

• Knowledge of the domain, of the programming language? Of a framework?
• What knowledge do you think might be needed to better understand this code?

Second thoughts?

What's the most disorientating thing so far? This can be something about the Code Reading Club process or the code sample we are looking at.

Is something confusing or worrying you? Are you feeling excited or uneasy?

Note down 1 or 2 thingsIndependently2 minutes

Second thoughts?

Syntax knowledge

The goal of this exercise is to practice to make sure everyone in club is familiar with syntactic elements of the code.

Examine syntaxIndependently5 minutes

Look at the code and examine syntactic elements. Do you know the meaning of all elements?

You can use these questions as a guide:

• Is it clear to you what the role of each block in the code is (function, condition, repetition etc)?
• Do you recognize all operators?
• Take the remainder of the time to think about what other things are unfamiliar.

Syntax knowledge

DiscussTogether5 minutes

Talk about unfamiliar constructs.

Were there constructs that were unfamiliar?

• If so, are there members of the group who know the meaning?
• If not, can you look up the constructs?

Why are the syntactic constructs unfamiliar?

Are they ideosyncratic to this language or code base?

Code structure

The goal of this exercise is to be a concrete thing to *do* when looking at new code for the first time. New code can be scary, doing something will help!

Examine structureIndependently8 minutes

Highlight the places where they are defined a draw links to where they are used. Use 3 different colours.

• Code to annotate

• Variables
• Functions / Methods
• Classes / Instantiation

Code structure

DiscussTogether10 minutes

• Did anyone have trouble deciding what constituted a variable, function or class?
• What patterns are visible from the colors and links only?
• How does the data flow through the code?
• What parts of the code seem to warrant more attention?

Content

Identify important linesIndependently5 minutes

Important can mean whatever you want it to. If it's helpful, try to think of it as a line that you might highlight when reading a text.

• Identify the 4 lines you consider most important
• Note those lines down on your board
• Think about why you chose them

We'll dot vote our line numbers together and discuss choices in the next exercise

Content

DiscussTogether8 minutes

Discuss in the group:

• lines covered by many people?
• lines named but not by a lot of people
• Agree less than 8 of the most important lines

Take turns in the group, and let every member talk about the code for 30 seconds (could also be one sentence each). Try to add new information and not repeat things that have been said, and repeat until people do not know new things anymore.

Summary

SummariseIndependently5 minutes

The goal of this exercise is to think about the core purpose or function of this code.

• try to write down the essence of the code in a few sentences

Summary

DiscussTogether8 minutes

• topics covered by many vs few
• strategies used to create the summary (e.g. method names, documentation, variable names, prior knowledge of system)

What now?

Code used for this session...

• faces.go from PhotoPrism an open-source photo tagging & search app

Code reading club resources: https://code-reading.org

Read Felienne's book! The Programmer's Brain

Start a club

Join a club

Get in touch hello@code-reading.org