Code
Reading
Club

with Katja, Felienne, Dan, Nick and Rupert

hello@codereading.club | https://codereading.club

Code
Reading
Club

What is Code Reading Club?

• Code of conduct
• codereading.club/conduct
• Group workspace
• Code in annotation tool

Code
Reading
Club

How it will work

• Grab a copy of the code (paper or digital)
• I'll keep the exercises & timer posted on my screenshare
• Join the group workspace (make a personal board for notes if you want)
• Make independent notes
• After each exercise copy any thoughts you want to share the group board

First glance

First glance

Glance at the code1 minuteIndependently

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

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

First glance

Discuss8 minutesTogether

It might be tempting for some people to start talking about the big picture, but for this exercise we focus on the details we notice, rather than attempt to summarise.

Talk about why things might have jumped out for different people.

• How do those initial observations help with deciding what to look at next?
• What lines, facts or concepts were noticed by many vs. few people in the group?

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?

What are we thinking?

This is a chance to get to know each other. It's important to be aware of who you are sharing this space with - so the club can be a success for everyone.

Take a few minutes to think about what's on your mind.

Is there something you want to share with the group about yourself?

Is there something you are unsure or curious about right now?

What are we thinking?

What are we thinking?

Discuss5 minutesTogether

Share our expectations for the session

Naming things

If you ask 2 developers to name a thing, there is only a 7% chance they come up with the same name.

Dror Fietelson - "How developers choose names"

Naming things

Identify things that are named5 minutesIn Pairs

Use the annotation tool to highlight names. This is one method for discovering how the code fits together and its intentions.

Naming things

List names on the Jamboard5 minutesTogether

Some people add names

• Use a single text box for each name

Other people start grouping and de-duping

• Pull together in clusters and label the group with a sticky note
• No rules here - so if you want to include a name in another cluster, re-dupe!

Naming things

What can we learn from these names?5 minutesTogether

Continue adding thoughts on sticky notes while we talk

• Which come from the domain?
• Which come from constructs / concepts in programming?
• Which elements are related to each other, from the names only?

Naming things

Identify patterns5 minutesTogether

Talk about molds

• Are there names that are ambiguous when looked at without context?
• Are there any conventions followed or not followed with the naming?

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!

Code structure

Examine structure10 minutesIndependently

Highlight the places where things are defined a draw links to where they are used. Use different colours. There is no "right" way to do this excercise. Use your insticts to explore how the pieces of code flow.

• Code to annotate

Start by identifying

• Variables
• Functions / Methods
• Classes / Instantiation

Code structure

Present5 minutesOne person

Share your annotations

Talk through your process and what you discovered

Code structure

Add one new thing5 minutesOne at a time

• Did you 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?
• How did you choose which colours to use?
• What strategies did you use to identify different elements in the code?

Content

What does it mean to be important?

Your brain prefers to see things it already knows, so if you don't make decisions, you might focus on the least important parts.

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.

Content

Identify important lines5 minutesIndependently

• Identify the 4 lines you consider most important
• Use a single text box for each number
• Group same numbers together in a line
• Think about why you chose them

Content

Look at the code2 minutesTogether

Get a sense of

• lines covered by many people?
• lines named but not by a lot of people

Content

Present5 minutesOne person

Talk through your 4 line choices

Content

Add one new thing5 minutesOne at a time

• Did you choose a line because it worried you?
• Did you choose a line you understood, or one that confused you?
• Did you choose a line with a comment?
• Did you choose a return statement or a function declaration?

Summary

Summary

Summarise5 minutesIndependently

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

Discuss8 minutesTogether

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

Reflect on the session

If you have time, it's helpful to wrap up the session with a little reflection.

Note down things5 minutesTogether

• that went well or felt good
• you want to try to do differently next time because they didn't work or felt bad

Q & A and next steps

Code used for this session...

• Nunjucks template for Gov.uk Date input component.

Any questions?

Next steps

• Code reading club resources: https://codereading.club
• Read Felienne's book! The Programmer's Brain
• Start a club
• Join a club
• Get in touch - email: hello@codereading.club | twitter: @codereadingclub