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

Reading Code (JFokus)

Reading Code (JFokus)

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

February 06, 2024
Tweet

More Decks by Marit van Dijk

Other Decks in Programming

Transcript

  1. Reading Code
    JFokus - Feb 6, 2024
    https://maritvandijk.com/

    View full-size slide

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

    View full-size 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 full-size 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 full-size slide

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

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  9. Code Reading Club
    • Printed code sample

    • Structured exercises

    View full-size slide

  10. Examples of exercises
    • First glance

    • Identify components & relationships

    • Most important lines

    • Identify concepts

    • Summary

    View full-size slide

  11. Code Reading Club
    Learned about ...

    • reading code

    • other peoples' perspectives

    • noticing my own assumptions

    View full-size slide

  12. Reading Code

    View full-size slide

  13. Reasons code is confusing
    1. Lack of knowledge

    2. Lack of information

    3. Lack of processing power in the brain

    View full-size slide

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

    • Programming constructs / algorithms

    • Business domain
    • Domain concepts

    • Business logic

    View full-size slide

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

    • Research

    • Memorize

    View full-size slide

  16. Lack of information
    • Unknown details

    • Unfamiliar names

    • Code connected in unknown ways

    • Too many things at once

    View full-size slide

  17. Dealing with lack of information
    • Chunking

    View full-size slide

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

    • Too many variables

    View full-size slide

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

    • Dependency graph

    • State table

    View full-size slide

  20. Dependency graph

    View full-size 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 full-size slide

  22. Dimensions of code reading
    • Structure

    • Domain

    • Concepts

    • Context

    View full-size slide

  23. Structure
    Code is not read linearly

    View full-size slide

  24. Domain
    • Behavior

    • Data

    View full-size slide

  25. Reading Code
    The bigger picture

    View full-size slide

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

    • Using a new code base

    View full-size slide

  27. Reading Code
    • What does the code do?

    View full-size slide

  28. Reading Code
    A good place to start:

    • Check out the code

    View full-size slide

  29. Help in the IDE

    View full-size slide

  30. Help in the IDE
    • Project structure

    • README

    • Diagrams

    • Dependencies

    • Build & run

    View full-size slide

  31. Strategies
    • Identify components

    • Identify relationships / dependencies

    • Identify concepts

    • Gain context

    View full-size slide

  32. A slice of the application

    View full-size slide

  33. Find a starting point

    View full-size slide

  34. Find a starting point
    • Generic
    • Main method

    • Endpoint

    • Speci
    fi
    c
    • Error message / Exception

    • Logic / Functionality

    View full-size slide

  35. Help in the IDE

    View full-size slide

  36. Help in the IDE
    • Search

    • Navigate

    View full-size slide

  37. Strategies
    • A particular use case

    • Draw your own diagrams

    View full-size slide

  38. Reading Code
    Understanding a piece of code

    View full-size slide

  39. Reading Code
    • Structured exercises

    View full-size slide

  40. Help in the IDE

    View full-size slide

  41. Help in the IDE
    • Structure

    • Hints from your IDE

    • Tests

    • Refactor for understanding

    • Context

    View full-size slide

  42. Strategies
    • Dependency graph

    • State table

    • Context for git history

    View full-size slide

  43. Reading Code
    What's next?

    View full-size 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 full-size slide

  45. Let your tools help you

    View full-size slide

  46. ... and your brain

    View full-size slide

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

    View full-size 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 full-size 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 full-size 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 full-size 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 full-size 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 full-size slide

  53. Code reading exercise
    Code Structure: Roles of variables
    • (20 min) Together - Discuss the roles of variables

    View full-size slide

  54. Code reading exercise
    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?

    • Deeply nested deeply or
    fl
    at?

    • Lines that stand out?

    • How is whitespace used?

    • Are there gaps?

    • Large blobs of code?

    • What (other) anchors do you use to scan the code?

    View full-size slide

  55. Code reading exercise
    List of names
    • List all names in the codebase. Write all variable names down in a
    fi
    le, or on a
    piece of paper.

    • List names that the programmer chose (not the language designer), including
    variables, parameters, classes and functions/methods.

    • Create a table with the name & type (class, method, variable)

    View full-size slide

  56. Demo time:
    Understanding a
    piece of code

    View full-size slide

  57. Syntax highlighting & other hints
    Structure / Restructure
    Behavior
    Context

    View full-size slide

  58. Reading Code
    A slice of the application
    • Search

    View full-size slide

  59. A slice of the application
    • Search

    • Navigate

    View full-size slide

  60. Demo time:
    A slice of code

    View full-size slide

  61. Find a starting point
    Search
    Navigate

    View full-size slide

  62. Demo time:
    The big picture

    View full-size slide

  63. README
    Project structure
    Dependencies
    Diagrams

    View full-size slide

  64. Reading Code
    Introduction
    Cognitive processes:

    • Long term memory

    • Short term memory

    • Working memory

    View full-size slide

  65. Code reading exercise
    Cognitive processes
    Read a piece of code to determine what it does.

    While doing so, re
    fl
    ect on the mechanisms that you use:

    • Are you retrieving knowledge from Long Term Memory? If so, what info?

    • What information are you storing or ignoring?

    • Which parts of the code place a heavy load on your working memory?

    View full-size slide

  66. Reading Code
    Strategies:

    • Identify components

    • Identify relationships / dependencies

    • Identify concepts

    View full-size slide

  67. Reading Code
    Components & relationships:

    • Modules, packages, classes

    • Relationships / Dependencies

    View full-size slide

  68. Reading Code
    Concepts

    • Business domain

    • Programming domain

    Create list(s) and research

    View full-size slide

  69. Understanding a piece of code
    • Syntax

    View full-size slide

  70. Understanding a piece of code
    • Structure

    View full-size slide

  71. Understanding a piece of code
    • Restructure

    View full-size slide

  72. Understanding a piece of code
    • Behavior

    View full-size slide

  73. Understanding a piece of code
    • Context

    View full-size slide

  74. Structure
    Code is not read linearly

    View full-size slide

  75. Structure
    • Collapse / expand

    • Reformat

    • Move code around

    View full-size slide

  76. Domain
    • Behavior

    • Data

    View full-size slide

  77. Domain
    • Data

    View full-size slide

  78. Domain
    • Tests

    • Debugger

    • Run the application

    View full-size slide

  79. Domain
    Take notes

    Draw diagrams

    Read documentation

    View full-size slide

  80. Concepts
    Take notes

    Research

    Read documentation

    View full-size slide

  81. Context
    • Search

    • Navigate

    • Git blame

    View full-size slide

  82. Reading Code
    Diagrams

    • Create diagrams of dependencies

    • UML diagrams

    • Decision diagrams

    View full-size slide

  83. Reading Code
    Strategies:

    • Clone & run

    • Look at the structure

    • Identify components & dependencies

    • Identify concepts

    • Draw diagrams

    View full-size slide

  84. Reading code
    Summary
    • Clone & build project

    • Components & Concepts

    • Relationships / Dependencies

    • Find a place to start

    • Search

    • Navigate
    • Structured exercises

    • Syntax

    • Structure / Restructure

    • Behavior

    • Context

    View full-size slide

  85. https://xkcd.com/1053/

    View full-size slide

  86. Reading Code
    The bigger picture
    A good start:

    • Check out the code

    • See if you can build it

    View full-size slide

  87. Reading Code
    The bigger picture
    • Draw your own diagrams

    • Write down questions (and
    fi
    nd answers)

    • Write down suggestions (maybe)

    View full-size slide

  88. Reading Code
    Down to the details
    • Draw diagrams /
    fl
    owcharts

    • Write down questions (and
    fi
    nd answers)

    • Write down suggestions (maybe)

    View full-size slide

  89. Reading Code
    • Syntax

    View full-size slide

  90. Reading Code
    • Structure

    View full-size slide

  91. Reading Code
    • Restructure

    View full-size slide

  92. Three types of structural components:

    • object components, which are used to create meaningful abstractions (user-
    created data types, structs or classes)

    • functional components in which execution is grouped, like methods or
    functions.

    • singular components that are variables or constants not contained in either
    objects or functional components

    View full-size slide

  93. Di
    ff
    erent relationships between components:

    • Object components

    • Inheritance

    • Contain functional components as methods and classes

    • Functional components

    • Use objects as parameters

    • Call static methods de
    fi
    ned on classes

    • Can call each other, creating a dependency

    • Override

    • Use singular components

    • Singular components

    • Do not depend on the other 2 types of components

    View full-size slide

  94. Informal relationships in code

    • Connections based on names and comments, e.g. “this class is like that
    class; we should consider merging them”

    • Connections based on parameters

    • Functional components can be connected when they use the same
    parameters frequently, which Fowler calls a Data Clump.

    • Functions can be similar because they operate on the same type of objects.

    View full-size slide

  95. Code reading exercise
    List all components
    Create a list of the components of the code:

    • object components, which are used to create meaningful abstractions (user-
    created data types, structs or classes)

    • functional components in which execution is grouped, like methods or
    functions.

    • singular components that are variables or constants not contained in either
    objects or functional components

    For each type, create a table with component name, # lines of code, size (S/M/L)

    View full-size slide

  96. Reading Code
    Agenda
    • Understanding a piece of code
    • Exercises for deliberate practice

    • Hints from your IDE

    • A slice of the application
    • Find a place to start

    • Search & navigate

    • The bigger picture
    • Understanding a codebase

    • and the context

    View full-size slide

  97. Reading Code
    Introduction
    • Let's look at various strategies for di
    ff
    erent tasks

    View full-size slide

  98. Reading Code
    The bigger picture
    Let's look at how the IDE can help!

    View full-size slide

  99. Reading Code
    The bigger picture
    Example: Spring Petclinic

    • Build (Maven/Gradle)

    • README

    • Project structure

    • Architectural pattern: MVC

    • Diagrams

    • Run locally

    View full-size slide

  100. Reading Code
    The bigger picture
    Example: Cucumber-jvm

    • Build

    • README / CONTRIBUTING

    • Dependencies between modules

    • Concepts

    View full-size slide

  101. Reading Code
    The bigger picture
    • Clone and run

    • README

    • Project structure

    • Components & dependencies

    • Diagrams

    • Concepts

    View full-size slide

  102. Reading Code
    Down to the details
    Let's look at how the IDE can help!

    View full-size slide

  103. Reading Code
    Down to the details
    Example: Spring Petclinic

    • Main method

    • Endpoints

    View full-size slide

  104. Reading Code
    Down to the details
    Example: Cucumber-jvm

    • Error message

    View full-size slide

  105. Reading Code
    Understanding a piece of code
    Let's look at how the IDE can help!

    View full-size slide

  106. Reading Code
    Understanding a piece of code
    Example: Cucumber-jvm

    • Synxtax highlighting

    • IDE hints

    • Documentation in the code

    • Structure / Restructure

    View full-size slide

  107. Reading Code
    Understanding a piece of code
    Example: Spring Petclinic

    • Behavior

    • Tests

    • Debugger

    • Context

    • Git history

    • Commit

    View full-size slide

  108. Reading Code
    Understanding a piece of code
    • Syntax highlighting & other hints

    • Structure / Restructure

    • Behavior

    • Context

    View full-size slide