Slide 1

Slide 1 text

Code reading workshop SoCraTes Germany - August 22th, 2024 https://maritvandijk.com/

Slide 2

Slide 2 text

Code reading workshop Introduction • We spend more time reading code than writing code

Slide 3

Slide 3 text

Code reading workshop Introduction • We spend more time reading code than writing code • But we don't practice reading code (much)

Slide 4

Slide 4 text

Code reading workshop Introduction • We spend more time reading code than writing code • But we don't practice reading code (much) • What if we practice reading code explicitly?

Slide 5

Slide 5 text

Code reading workshop Introduction • We spend more time reading code than writing code • What if we practice reading code explicitly? • Code Reading Club https://codereading.club/

Slide 6

Slide 6 text

Code reading workshop Introduction • We spend more time reading code than writing code • What if we practice reading code explicitly? • Code Reading Club • The Programmer's Brain - Felienne Hermans

Slide 7

Slide 7 text

Code reading workshop Introduction

Slide 8

Slide 8 text

Code reading workshop Expectations (1) (2 mins) Independently - Note down one thing about today's code reading club session in a sticky note... ... that you are looking forward to or excited about ... that you are worried or confused about

Slide 9

Slide 9 text

Code reading workshop Expectations (2) (5 mins) Together - Discuss Give everyone a chance to read out their hopes and fears Use the remaining time to discuss collectively what you want to get out of the session

Slide 10

Slide 10 text

Code reading workshop First glance (1) The goal of this exercise is to practice to get a fi rst impression of code and to act upon that. We all have di ff erent instincts and strategies for where to start when faced with a new piece of code. It doesn't matter how trivial you think the fi rst and second things you noticed are. (1 min) Independently - Glance at the code It's important that this is an immediate reaction. Right away, note down the fi rst thing that catches your eye. Then note down the second thing that catches your eye. Take the remainder of the minute to think about why you noticed those things fi rst.

Slide 11

Slide 11 text

Code reading workshop First glance (2) (5 mins) Together - Discuss the results Talk about why things might have jumped out for di ff erent people. • 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? Re fl ect 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?

Slide 12

Slide 12 text

Code reading workshop Code Structure: Dependency Graph (1) The goal of this exercise is to be a concrete thing to do when looking at new code for the fi rst time. New code can be scary, doing something will help! (5 mins) Independently - Examine structure Variables 1. Go through the code and underline all variables 2. Then draw a link between variables and their uses Function / method calls 3. Go through the code and circle all methods / function calls 4. Then draw a link between methods and their invocations Instantiation 5. Go through the code and draw a box around all instances of classes 6. Then draw a link between classes and their instances

Slide 13

Slide 13 text

Code reading workshop Code Structure: Dependency Graph (2) (10 mins) Together - Discuss the results • Did anyone have trouble deciding what constituted a variable, function or class? • What patterns are visible from the use of variables / methods and links between them only? • How does the data fl ow through the code? • What parts of the code seem to warrant more attention?

Slide 14

Slide 14 text

Code reading workshop Code Structure: Dependency Graph (3) Do try this at home Normally, you would use your IDE for syntax highlighting. In addition, create a graph or diagram of how data fl ows through your application, where variables are used, methods are called, etc.

Slide 15

Slide 15 text

Code reading workshop Code Structure Code is not read linearly. We scan the code, rather than read it word for word. The "shape" or structure of the code can help us do that. (5 min) Together - Discuss the code structure • What is the structure of the code? • Is the code nested deeply or it is fl at? • Are there any lines that stand out? • How is whitespace used to structure the code? • Are there gaps in the code? • Are there large blobs of code? • What (other) anchors do you use to scan the code?

Slide 16

Slide 16 text

Code reading workshop Code Structure Do try this at home Use (re)formatting in your IDE. Or collapse/expand code as needed.

Slide 17

Slide 17 text

Code reading workshop Content: Concepts (1) (5 mins) Individually - Central thematic concepts Individually name the 5 most central concepts of the code. These could be names, themes, classes, or information found in comments. These could be algorithms, data structures, assumptions or techniques. Note: there are no right or wrong answers here! We are not looking for the correct 5 concepts, we are together trying to practice reading code and gain insights into how each other people approach and understand reading code.

Slide 18

Slide 18 text

Code reading workshop Content: Concepts (2) (10 mins) Together - Discuss • Topics covered by many vs few • Strategies used to decide (e.g. method names, documentation, variable names, prior knowledge of system)

Slide 19

Slide 19 text

Code reading workshop Content: Concepts (5) Do try this at home When reading new (to you) code, create a list of concepts. Check the ones that are familiar Research the ones that are not. Use this as a "checklist" to prevent falling down rabbit holes. (Maybe contribute back to documentation what you've learned?)

Slide 20

Slide 20 text

Code reading workshop Content: Most important lines (1) The goal of this exercise is to start to think about which lines in the code de fi ne its essence, have the biggest impact or need to be paid close attention to. (5 mins) Independently - Identify most important lines Brie fl y discuss what it means to be important as a group (if you want to) Then, identify the 5 lines you consider most important

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

Code reading workshop Content: Most important lines (2) (10 mins) Together - Discuss • Lines covered by many people? • Lines named but not by a lot of people • Discuss why particular lines were chosen • Can we agree on < 8 of the most important lines? 1 15 29 2 16 30 3 17 31 4 18 32 5 19 33 6 20 34 7 21 35 8 22 36 9 23 37 10 24 38 11 25 39 12 26 40 13 27 41 14 28 42

Slide 23

Slide 23 text

Code reading workshop Summary (1) The goal of this exercise is to think about the core purpose or function of this code. (5 mins) Independently - Summarise Try to write down the essence of the code in a few sentences

Slide 24

Slide 24 text

Code reading workshop Summary (2) (10 mins) Together - Discuss • Topics covered by many vs few • Strategies used to create the summary (e.g. method names, documentation, variable names, prior knowledge of system)

Slide 25

Slide 25 text

Code reading workshop Re fl ect on the session Let's wrap up the session with a little re fl ection (5 mins) Together - note down things about the session • What went well or felt good? • What would you to try to do di ff erently next time because they didn't work or felt bad?

Slide 26

Slide 26 text

Code reading workshop Next steps (10 mins) Together - Discuss • Now that you have attended this workshop, would you consider doing this more often? Why / why not? • What would you get out of doing code reading sessions? • How could you apply what you learned in your daily work?

Slide 27

Slide 27 text

Code reading workshop Slides and more https://maritvandijk.com/presentations/code-reading/