Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Code reading (workshop)

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.

Marit van Dijk

July 13, 2023
Tweet

More Decks by Marit van Dijk

Other Decks in Programming

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