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
   GOTO Copenhagen - Oct 3, 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 or changing functionality
   
   •
   fi
   xing bugs
   
   • understanding a new code base
   
   • doing code reviews
   
   • learning new things
   
   • 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
    • Joined a code reading club
    
    • So many insights!
    

    View Slide

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

    View Slide

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

    View Slide

13. Reading Code
    Introduction
    

    View Slide

14. Reading Code
    Agenda
    • The bigger picture
    • Understanding a codebase
    
    • and it's context
    
    • Down to the details
    • Find a place to start
    
    • Search
    
    • Navigate from there
    
    • Understanding a speci
    fi
    c piece of code
    • Hints from your IDE
    
    • Exercises for deliberate practice
    

    View Slide

15. Reading Code
    The bigger picture
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

19. Reading Code
    The bigger picture
    • Background knowledge
    
    • Business domain
    
    • Programming domain
    

    View Slide

20. Reading Code
    The bigger picture
    • Read the documentation!
    
    • Do some research
    

    View Slide

21. Reading Code
    The bigger picture
    • Take notes!
    

    View Slide

22. Reading Code
    The bigger picture
    • Draw your own diagrams
    
    • Write down questions (and
    fi
    nd answers)
    
    • Write down suggestions (maybe)
    

    View Slide

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

    View Slide

24. Reading Code
    The bigger picture
    Science:
    
    • Chunking
    

    View Slide

25. Reading Code
    The bigger picture
    But
    fi
    rst:
    
    • Check out the code
    
    • See if you can build it
    

    View Slide

26. Demo time:
    
    
    The big picture
    

    View Slide

27. README
    
    
    Project tool window
    
    
    Dependency Matrix
    
    
    Diagrams
    

    View Slide

28. Reading Code
    Down to the details
    

    View Slide

29. Reading Code
    Down to the details
    • Find a starting point
    
    

    View Slide

30. Reading Code
    Down to the details
    • Search
    

    View Slide

31. Reading Code
    Down to the details
    • Navigate
    

    View Slide

32. Demo time:
    
    
    Down to the details
    

    View Slide

33. Find a starting point
    
    
    Search
    
    
    Navigate
    

    View Slide

34. Reading Code
    Understanding a piece of code
    

    View Slide

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

    View Slide

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

37. Reading Code
    Understanding a piece of code
    • Syntax
    
    

    View Slide

38. Reading Code
    Understanding a piece of code
    • Structure
    
    

    View Slide

39. Reading Code
    Understanding a piece of code
    • Restructure
    
    

    View Slide

40. Reading Code
    Understanding a piece of code
    • Behavior
    
    

    View Slide

41. Reading Code
    Understanding a piece of code
    • Context
    
    

    View Slide

42. Demo time:
    Understanding a
    
    
    piece of code
    

    View Slide

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

    View Slide

44. Reading code
    Summary
    • Clone & build project
    
    • Components & Concepts
    
    • Relationships / Dependencies
    
    • Find a place to start
    
    • Search
    
    • Navigate
    • Find a way to start
    
    • Structured exercises
    
    • Syntax
    
    • Structure / Restructure
    
    • Behavior
    
    • Context
    

    View Slide

45. Reading Code
    Next steps
    • Do try this at home
    
    

    View Slide

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

    View Slide