Code reading (workshop)

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 SoCraTes UK - June 1st, 2023 https://maritvandijk.com/
2. Code reading workshop Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish
3. Code reading workshop Introduction • We spend more time reading code than writing code
4. Code reading workshop Introduction • We spend more time reading code than writing code • 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 by Felienne Hermans 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 by Felienne Hermans • The Programmer's Brain by Felienne Hermans
7. Code reading workshop Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish
8. 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
9. 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
10. Code reading workshop Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish
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 Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish
14. Code reading workshop Code Structure (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! (12 mins) Independently - Examine structure Variables Go through the code and circle all variables in red Then draw a link between variables and their uses Function / method 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
15. Code reading workshop Code Structure (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 colors and links only? • How does the data fl ow through the code? • What parts of the code seem to warrant more attention?
16. Code reading workshop Code Structure (alt) • (20 mins) Together - Discuss the roles of variables
17. Code reading workshop Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish
18. Code reading workshop Content (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. (8 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
19. Code reading workshop Content (2) (10 mins) Together - Discuss Discuss in the group: • Lines covered by many people? • Lines named but not by a lot of people • Discuss why particular lines were chosen • Can we agree on less than 8 of the most important lines? 1 15 5 29 3 2 2 16 3 30 1 3 17 31 4 4 18 9 32 5 19 33 6 20 3 34 7 2 21 35 8 3 22 9 36 9 2 23 3 37 2 10 24 2 38 2 11 25 39 4 12 1 26 7 40 7 13 27 1 41 14 28 2 42
20. Code reading workshop Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish
21. 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
22. 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)
23. Code reading workshop Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish
24. 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?
25. Code reading workshop Next steps (1) If we have time, we can optionally discuss the following (5 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?
26. Code reading workshop Links https://maritvandijk.com/presentations/code-reading/
27. Code reading workshop Agenda • 14:30 Introduction (5 min) • 14:35 Expectations (10 min) (hand out copies of sample) • 14:45 First glance (10 min) • 14:55 Code structure (25 min) • 15:20 Content (20 min) • 15:40 Summary (15 min) • 15:55 Re fl ect (5 min) • 16:00 Finish