Code reading workshop (JavaZone)

by Marit van Dijk

Slide 1

Slide 1 text

Code reading workshop JavaZone - Sept 5th, 2023 https://maritvandijk.com/

Slide 2

Slide 2 text

Code reading workshop Agenda • 13:30 Introduction (5 min) • 13:35 Expectations (10 min) (hand out copies of sample) • 13:45 First glance (10 min) • 13:55 Code structure (20 min) • 14:15 Concepts (30 min) • 14:45 Content (15 min) • 15:00 Summary (15 min) • 15:15 Re fl ect (15 min) • 15:30 Finish

Slide 3

Slide 3 text

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

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)

Slide 5

Slide 5 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 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 https://codereading.club/

Slide 7

Slide 7 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 8

Slide 8 text

Slide 9

Slide 9 text

Slide 10

Slide 10 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 11

Slide 11 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 12

Slide 12 text

Slide 13

Slide 13 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 14

Slide 14 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 15

Slide 15 text

Slide 16

Slide 16 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 17

Slide 17 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 18

Slide 18 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 19

Slide 19 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 20

Slide 20 text

Slide 21

Slide 21 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. 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 22

Slide 22 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 23

Slide 23 text

Code reading workshop Content: Concepts (3) (5 mins) Individually - Central programming concepts Each participant gets 5 minutes to individually name the 5 most central programming concepts of the code. These could be algorithms, data structures, assumptions or techniques. Again here, no right and wrong! These questions are conversation starters. We can learn from each other's perspectives.

Slide 24

Slide 24 text

Code reading workshop Content: Concepts (4) (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 25

Slide 25 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. You can use this as a "checklist" to prevent falling down rabbit holes. (Maybe contribute back to documentation what you've learned?)

Slide 26

Slide 26 text

Slide 27

Slide 27 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 28

Slide 28 text

No content

Slide 29

Slide 29 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 30

Slide 30 text

Slide 31

Slide 31 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 - Summarize Try to write down the essence of the code in a few sentences

Slide 32

Slide 32 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 33

Slide 33 text

Slide 34

Slide 34 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 35

Slide 35 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 36

Slide 36 text

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