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

Reading code

Reading code

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 talk we will discuss the benefits of deliberately practicing reading code in a code reading club or session without an IDE, as well as common strategies to navigate a new codebase and familiarise ourselves with the code using the IDE.

Marit van Dijk

November 10, 2023
Tweet

More Decks by Marit van Dijk

Other Decks in Programming

Transcript

  1. Reading Code
    Øredev - Nov 10, 2023
    https://maritvandijk.com/

    View Slide

  2. Reading Code
    • We spend more time reading code than writing code

    View Slide

  3. Reading Code
    We read code when:

    • adding features


    fi
    xing bugs

    • understanding a new system

    • doing code reviews

    • learning new technologies

    • etc.

    View Slide

  4. Reading Code
    "developers on average spend as much as 58% of their time comprehending
    existing source code"

    -

    Felienne Hermans,
    The Programmer's Brain

    View Slide

  5. Reading Code
    • We spend more time reading code than writing code

    • But we don't practice reading code explicitly (much)

    View Slide

  6. Reading Code
    "How to teach programming (and other things)?" by Felienne Hermans
    https://www.youtube.com/watch?v=g1ib43q3uXQ

    View Slide

  7. Reading Code
    • What if we practice reading code explicitly?

    View Slide

  8. Code Reading Club
    • Code Reading Club
    https://codereading.club/

    View Slide

  9. Code Reading Club
    • Printed code

    • Structured exercises

    View Slide

  10. Examples of exercises
    • First glance

    • Identify components & relationships

    • Most important lines

    • Identify concepts

    • Summary

    View Slide

  11. Code Reading Club
    Learned about ...

    • reading code

    • other peoples' perspectives

    • noticing my own assumptions

    View Slide

  12. Reading Code

    View Slide

  13. Reasons code is confusing
    1. Lack of knowledge

    2. Lack of information

    3. Lack of processing power in the brain

    View Slide

  14. Lack of knowledge
    • Programming domain
    • Language / syntax

    • Programming constructs / algorithms

    • Business domain
    • Domain concepts

    • Business logic

    View Slide

  15. Dealing with a lack of knowledge
    • Create a list

    • Research

    • Memorize

    View Slide

  16. Lack of information
    • Unknown details

    • Unfamiliar names

    • Code connected in unknown ways

    • Too many things at once

    View Slide

  17. Dealing with lack of information
    • Chunking

    View Slide

  18. Lack of processing power in the brain
    • Too many processing steps

    • Too many variables

    View Slide

  19. Dealing with lack of processing power in the brain
    • Memory aids

    • Dependency graph

    • State table

    View Slide

  20. Dependency graph

    View Slide

  21. State table
    public class NestedLoop {
    public static void main(String[] args) {
    for (int i = 0; i < 2; i++) {
    System.out.println("i is: " + i);
    for (int j = 0; j < 2; j++) {
    System.out.println("j is: " + j);
    }
    }
    }
    }

    View Slide

  22. Reading Code
    Understanding a piece of code

    View Slide

  23. Reading Code
    • Structured exercises

    View Slide

  24. Dimensions of code reading
    • Structure

    • Domain

    • Concepts

    • Context

    View Slide

  25. Structure
    Code is not read linearly

    View Slide

  26. Domain
    • Behavior

    • Data

    View Slide

  27. Concepts

    View Slide

  28. Reading Code
    • Context

    View Slide

  29. Help in the IDE
    • Structure / Restructure

    • Domain

    • Behavior

    • Syntax highlighting & hints

    • Context

    View Slide

  30. Strategies
    • Structure

    • Identify components & relationships

    • Identify concepts

    • Gain context

    View Slide

  31. A slice of the application

    View Slide

  32. Find a starting point

    View Slide

  33. Find a starting point
    • Generic
    • Main method

    • Endpoint

    • Speci
    fi
    c
    • Error message / Exception

    • Logic / Functionality

    View Slide

  34. Help in the IDE
    • Search

    • Navigate

    View Slide

  35. Strategies
    • A slice of the application

    View Slide

  36. Reading Code
    The bigger picture

    View Slide

  37. Understanding a new code base
    • Joining a new team / organisation

    • Using a new code base

    View Slide

  38. Reading Code
    • What does the code do?

    View Slide

  39. Context

    View Slide

  40. Reading Code
    A good place to start:

    • Check out the code

    • See if you can build it

    View Slide

  41. Help in the IDE
    • README

    • Project structure

    • Dependencies

    • Diagrams

    View Slide

  42. Strategies
    • Identify components

    • Identify relationships / dependencies

    • Identify concepts

    • Gain context

    View Slide

  43. Reading Code
    What's next?

    View Slide

  44. Structured exercises
    • Code Reading Club: https://codereading.club/

    • Code Reading Club Resources:

    https://github.com/CodeReadingClubs/Resources

    • The Programmer's Brain - Felienne Hermans

    • Code Reading in Practice - Felienne Hermans & Gien Verschatse

    View Slide

  45. Let your tools help you
    • Structure/Restructure

    • Reformat

    • Refactor

    • Tests & Debugging

    • Git history

    • Search & Navigate

    • Diagrams

    • ...

    View Slide

  46. ... and your brain

    View Slide

  47. Reading code
    Slides & More
    https://maritvandijk.com/presentations/reading-code/

    View Slide

  48. Code reading exercise
    First glance
    The goal of this exercise is to practice getting a
    fi
    rst impression of code.

    (1 min) Independently - Glance at the code
    Note down the
    fi
    rst thing that catches your eye.

    Then note the second thing that catches your eye.

    Think about why you noticed those things
    fi
    rst.

    View Slide

  49. Code reading exercise
    Dependency graph
    The goal of this exercise is to get a feel for the structure of the code.

    (5 min) 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

  50. Code reading exercise
    Most important lines
    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

  51. Code reading exercise
    Concepts
    (5 min) Individually - Central thematic concepts
    Name the 5 most central concepts of the code. These could be names,
    themes, classes, or information found in comments.

    View Slide

  52. Code reading exercise
    Summary
    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