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/
   

   View Slide

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
   

   View Slide

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

   View Slide

4. Code reading workshop
   Introduction
   • We spend more time reading code than writing code
   
   • What if we practice reading code explicitly?
   
   

   View Slide

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/
   

   View Slide

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
   
   

   View Slide

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
   

   View Slide

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
   
   

   View Slide

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
   

   View Slide

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
    

    View Slide

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.
    

    View Slide

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?
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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?
    
    

    View Slide

16. Code reading workshop
    Code Structure (alt)
    • (20 mins) Together - Discuss the roles of variables
    

    View Slide

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
    

    View Slide

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
    
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    
    

    View Slide

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)
    
    

    View Slide

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
    

    View Slide

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?
    
    

    View Slide

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?
    
    

    View Slide

26. Code reading workshop
    Links
    https://maritvandijk.com/presentations/code-reading/
    

    View Slide

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
    

    View Slide