$30 off During Our Annual Pro Sale. View Details »



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

March 15, 2023

More Decks by Marit van Dijk

Other Decks in Programming


  1. Code reading workshop
    JUG Switzerland - March 14th, 2023

    View Slide

  2. Welcome!

    1. Join the Miro Board

    2. Select annotation method:

    * On paper

    * Annotation tool

    * Download file

    Try to refrain from reading the code for now!

    View Slide

  3. Code reading workshop
    • Welcome!

    • Setting the scene

    View Slide

  4. Code reading workshop
    Setting the scene (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

  5. Code reading workshop
    Setting the scene (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

  6. Code reading workshop
    • Welcome!

    • Setting the scene

    • First glance

    • Code structure

    • BREAK

    • Content

    • Summary

    • Re

    View Slide

  7. Code reading workshop
    First glance (1)
    The goal of this exercise is to practice to get a
    rst impression of code and to act upon that. We all have di
    instincts and strategies for where to start when faced with a new piece of code. It doesn't matter how trivial you
    think the
    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
    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

    View Slide

  8. Code reading workshop
    First glance (2)
    (5 mins) Together - Discuss the results
    Talk about why things might have jumped out for di
    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?

    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

  9. 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
    rst time. New code can
    be scary, doing something will help!

    (12 mins) Independently - Examine structure
    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

    Go through the code and circle all instances of classes in green

    Then draw a link between classes and their instances

    View Slide

  10. 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
    ow through the code?

    • What parts of the code seem to warrant more attention?

    View Slide

  11. Code reading workshop
    Content (1)
    The goal of this exercise is to start to think about which lines in the code de
    ne its essence, have the biggest impact
    or need to be paid close attention to.

    (8 mins) Independently - Identify most important lines
    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

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

    • Agree on less than 8 of the most important lines

    • Take turns in the group, and let every member talk about the code for 30 seconds (or less/more, could also be one
    sentence each). Try to add new information and not repeat things that have been said, and repeat until people do
    not know new things anymore.

    View Slide

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

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

    View Slide

  15. Code reading workshop
    ect on the session
    Let's wrap up the session with a little re

    (5 mins) Together - note down things about the session
    • What went well or felt good?

    • What would you to try to do di
    erently next time because they didn't work or felt bad?

    View Slide

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

  17. Code reading workshop

    View Slide