exercises.md

This page contains a set of exercises which can be used in Code Reading Clubs. Of course, your club does not need to use all exercises, they are meant as a starting point. If you are trying out variants, do let us know! For now we have divided them into basic and advanced. Advanced exercises can be used in clube that have been running for a while, or when doing a second seccion on the same code snippet.

Basic Exercises

You will need:

• two printed copies of the code for today's club
• coloured paper and scissors
• acetate and something to write on it with
• coloured pens, crayons or pencils
• or: a tablet and tablet pen with a PDF of the code

First glance

The goal of this exercise is to practice to get a first impression of code and to act upon that.

Look at the code (1 min)

Look at the code at a glance, really not more than 1 minute. Then try to answer these questions:

• What is the first thing that catches your eye? Why is that?

• What is the second think that you see? Why?

• Are these two things (variables, classes, prorgramming concepts) related?

Discuss the results (10 mins)

Discuss the results as a group. What lines of facts or concepts were chosen by everyone versus by only a few people?

Reflect also on what kind of knowledge did you use in this exercise? Knowledge of the domain, of the progamming language? Of a framework? What knowledge do you think might be needed to better understand this code?

Code structure

Examine structure (10 mins)

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!

Color variables

• Go through the code and circle all variables in red
• Then draw a link between variables and their uses

Color method/function calls

• Go through the code and circle all methods in blue
• Then draw a link between methods and their invocations

Instantiation

• Go through the code and circle all instances of classes in green
• Then draw a link between classes and their instances

Discuss the results (10 mins)

1. What patterns are visible from the colors and links only?
2. What parts of the code warrant more attention based on the colors?

Content

All variable/class/method names (5 mins)

Go through the code mechanically and create a list of all identifier names in the snippet. Of you have done the "examine structure" exercise before, this should be relatively quick and easy.

Discussion (10 mins)

Discuss in the group:

• What can we learn from these names?
• Which names are related to each other, from the names only?
• Are there names that are ambiguous when looked at without context?

A random line (5 mins)

Select a random line from the code in whatever way you like. Examine this line individually. What is the main idea of this line? What lines does it relate to and why?

Discussion (10 mins)

Discuss in the group:

• What is the 'scope' of the random line? What part of the code was seen as related?
• How does the line fit into the rest of the code base?

Identify most important lines (10 mins)

Define what it means to be important as a group, and then independently identify the 5 lines you consider most important.

Discussion (10 mins)

Discuss in the group:

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

Take turns in the group, and let every member talk about the code for 30 seconds (or less/more, 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. Save the last word for me protocol

Summarize in less than 10 sentences individually (10 mins)

1. Independently write down the essence of the code in a few sentences

Discussion (10 mins)

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

Summarize in less than 10 sentences (10 mins)

1. Create a summary together
2. Compare the summary with the available documentation (inside and outside the code)

• identify differences and similarities between the groups findings and the existing

Advanced Exercises

These exercises are more advanced, in the sense that you might need a bit more understanding of the code for these to make sense. This might be because the group is familiar with the code before the session, or because you are doing a second club on the same code snippet.

Code structure

Examine structure (5 mins)

Use one of the basic exercises to examine the structure of the code (such as circle variables and link them), or reuse the notes from the previous club. Individuallt study the patterns and think about what they tell you. What direction does the code 'flow' in? What parts stand out for lack of, or access of links?

Discussion (10 mins)

• Parts of the code covered by many vs few
• Strategies used to decide

Content

Central thematic concepts (5 mins)

Each participant gets 5 minutes to individually name the 5 most central concepts of the code. These could be names, themes, classes, or information found in comments.

Discussion (10 mins)

• Topics covered by many vs few
• Strategies used to decide (e.g. method names, documentation, variable names, prior knowledge of system)

Central programming concepts (5 mins)

Each participant gets 5 minutes to individually name the 5 most central computer science concepts of the code. These could be algorithms, data structures, assumptions or techniques.

Discussion (10 mins)

• Topics covered by many vs few
• Strategies used to decide (e.g. method names, documentation, variable names, prior knowledge of system)

The 'why' of the code

Reexamine the code snippet and list decisions and intentions of the creator(s) of the code. For example a decision to use a certain design pattern ir use a certain library or API?

• What decisions were made in the creation of this code?
• What assumptions do these decisions rely on?

Discussion (10 mins)

Gather all decisions people made individually and discuss:

• Pros of these decisions
• Possible cons of these decisions
• Alternative solutions