Code reading workshop (JavaZone)

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
   JavaZone - Sept 5th, 2023
   https://maritvandijk.com/
   

   View Slide

2. 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
   

   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
   
   • But we don't practice reading code (much)
   
   

   View Slide

5. 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?
   
   

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

   View Slide

7. 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
   
   

   View Slide

8. 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
   
   • Code Reading in Practice - Felienne Hermans & Gien Verschatse
   (upcoming)
   

   View Slide

9. 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
   

   View Slide

10. 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

11. 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

12. 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
    

    View Slide

13. 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

14. 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

15. 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
    

    View Slide

16. 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
    

    View Slide

17. 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?
    

    View Slide

18. 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.
    

    View Slide

19. 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?
    

    View Slide

20. 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
    

    View Slide

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

    View Slide

22. 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)
    
    

    View Slide

23. 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.
    
    

    View Slide

24. 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)
    
    

    View Slide

25. 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?)
    
    

    View Slide

26. 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
    

    View Slide

27. 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
    
    

    View Slide

28. View Slide

29. 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
    

    View Slide

30. 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
    

    View Slide

31. 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

32. 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

33. 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
    

    View Slide

34. 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

35. 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?
    
    

    View Slide

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

    View Slide