Code Reading workshop - Software Cornwall

As developers, we spend a lot of time learning to write code, while spending little to no time learning to read code. Meanwhile, we often spend more time reading code than actually writing it. Shouldn’t we be spending at least the same amount of time and effort improving this skill? Deliberate practice can help us get better at reading code. Learning how to better read and understand code, can in turn teach us what makes code readable. This might even help us to write code that is easier to read.
In this workshop we will practice our code reading skills by reading an unfamiliar piece of code, using structured exercises. Participants will practice reading code, and take away knowledge about how they can continue to improve this important skill.

Transcript

1. Code reading workshop Software Cornwall - July 25th, 2024 https://maritvandijk.com/
2. Code reading workshop Introduction • We spend more time reading code than writing code
3. Code reading workshop Introduction • We spend more time reading code than writing code • But we don't practice reading code (much)
4. 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?
5. 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/
6. 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
7. Code reading workshop Introduction
8. Exercises Go to the Miro board: https://miro.com/app/board/uXjVKw8aEA0=/
9. 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
10. 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
11. 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.
12. 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?
13. Code reading workshop Code annotation tool Open the code snippet in the Code annotation tool 1. Open the Code annotation tool: https://annotate.codereading.club/#/ 2. Copy-paste the following link into the available fi eld: https://github.com/mlvandijk/cucumber-jvm/blob/ 4155907170cdc6264a1fe03789d2a034e029f294/cucumber-java/src/main/groovy/generate- annotations.groovy 3. Click the Annotate button
14. Code reading workshop Code annotation tool How to use the Code annotation tool 1. Highlight: • Select text • Select a color to highlight the text 2. Draw arrow: • Click highlighted text to start drawing an arrow • Click on other highlighted text to end the arrow
15. 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! (10 mins) Independently - Examine structure Variables 1. Go through the code and highlight all variables in yellow 2. Then draw a link between variables and their uses Function / method calls 3. Go through the code and highlight all methods / function calls in pink 4. Then draw a link between methods and their invocations Instantiation 5. Go through the code and highlight all instances of classes in blue 6. Then draw a link between classes and their instances
16. 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?
17. 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?
18. 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.
19. 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)
20. 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
22. 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
23. 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
24. 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)
25. 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?
26. 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?
27. Code reading workshop Slides and more https://maritvandijk.com/presentations/code-reading/