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.

Transcript

1. Reading Code
   GeeCON - Oct 19, 2023
   https://maritvandijk.com/
   

   View Slide

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

   View Slide

3. Reading Code
   Introduction
   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
   Introduction
   "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
   Introduction
   • We spend more time reading code than writing code
   
   • But we don't practice reading code explicitly (much)
   
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

9. Reading Code
   Introduction
   • Printed code
   
   • Structured exercises
   

   View Slide

10. Reading Code
    Introduction
    • So many insights!
    

    View Slide

11. Reading Code
    Introduction
    • But what about the IDE?
    

    View Slide

12. Reading Code
    Introduction
    

    View Slide

13. Reading Code
    Introduction
    Code can be confusing because of
    
    • Lack of knowledge
    
    • Lack of information
    
    • Lack of processing power in the brain
    
    

    View Slide

14. Reading Code
    Introduction
    Lack of knowledge
    
    • Business domain
    
    • Programming domain
    

    View Slide

15. Reading Code
    Introduction
    Dealing with a lack of knowledge
    
    • Create a list
    
    • Research
    
    • Study
    

    View Slide

16. Reading Code
    Introduction
    Lack of information
    
    • Unknown details
    
    • Unfamiliar names
    
    • Code connected in unknown ways
    
    • Too many things at once
    

    View Slide

17. Reading Code
    Introduction
    Dealing with lack of information
    
    • Chunking
    

    View Slide

18. Reading Code
    Introduction
    Lack of processing power in the brain
    
    • Overwhelmed
    

    View Slide

19. Reading Code
    Introduction
    Dealing with lack of processing power in the brain
    
    • Memory aids
    
    • Dependency graph
    
    • State table
    

    View Slide

20. Reading Code
    Introduction
    Dependency graph
    

    View Slide

21. Reading Code
    Introduction
    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);
    }
    }
    }
    }
    i j
    0 0
    0 1
    1 0
    1 1
    

    View Slide

22. Reading Code
    Understanding a piece of code
    

    View Slide

23. Reading Code
    Understanding a piece of code
    • Structured exercises
    

    View Slide

24. Reading Code
    Understanding a piece of code
    Examples of exercises
    
    • First glance
    
    • Identify components & relationships
    
    • Most important lines
    
    • Identify concepts
    
    • Summary
    

    View Slide

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

    View Slide

26. Reading Code
    Understanding a piece of code
    Structured exercises
    
    • 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

27. Reading Code
    Understanding a piece of code
    • Syntax
    
    

    View Slide

28. Reading Code
    Understanding a piece of code
    • Structure
    
    

    View Slide

29. Reading Code
    Understanding a piece of code
    • Restructure
    
    

    View Slide

30. Reading Code
    Understanding a piece of code
    • Behavior
    
    

    View Slide

31. Reading Code
    Understanding a piece of code
    • Context
    
    

    View Slide

32. Demo time:
    Understanding a
    piece of code
    

    View Slide

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

    View Slide

34. Reading Code
    A slice of the application
    

    View Slide

35. Reading Code
    A slice of the application
    • Find a starting point
    
    

    View Slide

36. Reading Code
    A slice of the application
    • Find a starting point
    
    • Generic
    
    • Main method
    
    • Endpoint
    
    • Speci
    fi
    c
    
    • Error message / Exception
    
    • Logic / Functionality
    

    View Slide

37. Reading Code
    A slice of the application
    • Search
    

    View Slide

38. Reading Code
    A slice of the application
    • Navigate
    

    View Slide

39. Demo time:
    A slice of code
    

    View Slide

40. Find a starting point
    Search
    Navigate
    

    View Slide

41. Reading Code
    The bigger picture
    

    View Slide

42. Reading Code
    The bigger picture
    • Onboarding to a new team / code base
    
    

    View Slide

43. Reading Code
    The bigger picture
    • What does the code do?
    
    

    View Slide

44. Reading Code
    Introduction
    A good place to start:
    
    • Check out the code
    
    • See if you can build it
    

    View Slide

45. Reading Code
    The bigger picture
    • What is the context?
    

    View Slide

46. Reading Code
    The bigger picture
    Strategies:
    
    • Identify components
    
    • Identify relationships / dependencies
    
    • Identify concepts
    

    View Slide

47. Demo time:
    The big picture
    

    View Slide

48. README
    Project structure
    Dependencies
    Diagrams
    

    View Slide

49. Reading Code
    Next steps
    • What's next?
    
    

    View Slide

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

    View Slide

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

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

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

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

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