Reading Code (BuildStuff)

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 BuildStuff, Nov 15th 2024 https://maritvandijk.com/
2. Disclaimer Contains Java
3. Reading Code • We spend more time reading code than writing code
4. Reading Code We read code when: • adding features • fi xing bugs • understanding a new system • doing code reviews • learning new technologies • etc.
5. Reading Code "developers on average spend as much as 58% of their time comprehending existing source code" - Felienne Hermans, The Programmer's Brain
6. Reading Code • We spend more time reading code than writing code • But we don't practice reading code explicitly (much)
7. Readability When we do talk about readability, it's often about writing readable code.
8. Reading Code "How to teach programming (and other things)?" by Felienne Hermans https://www.youtube.com/watch?v=g1ib43q3uXQ
9. Reading Code • What if we practice reading code explicitly?
10. Code Reading Club • Code Reading Club https://codereading.club/
11. The stars aligned Do you want to join our code reading club?
12. Code Reading Club • Printed code sample • Structured exercises
13. Examples of exercises • First glance • Identify components & relationships
14. Examples of exercises • First glance • Identify components & relationships • Most important lines
15. Examples of exercises • First glance • Identify components & relationships • Most important lines • Identify concepts
16. Examples of exercises • First glance • Identify components & relationships • Most important lines • Identify concepts • Summary
17. Code Reading Club Learned about ... • reading code
18. Code Reading Club Learned about ... • reading code • other peoples' perspectives
19. Code Reading Club Learned about ... • reading code • other peoples' perspectives • making my own assumptions explicit https://maritvandijk.com/code-reading-club/
20. Reading Code
21. Reasons why code is confusing 1. Lack of knowledge 2. Lack of information 3. Lack of processing power in the brain
22. Cognitive processes • Long term memory • Short term memory • Working memory
23. Lack of knowledge • Programming domain • Language / syntax • Programming constructs / algorithms • Business domain • Domain concepts • Business logic
24. Dealing with a lack of knowledge • Create a list • Research • Memorise (if relevant)
25. Lack of information • Unknown details • Unfamiliar names • Code connected in unknown ways • Too many things at once
26. Dealing with lack of information • Chunking
27. Dealing with lack of information • Chunking • Concepts & patterns
28. Lack of processing power in the brain • Too many processing steps • Too many variables
29. Dealing with lack of processing power in the brain • Memory aids • Dependency graph • State table
30. Dependency graph
31. 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); } } } }
32. Dimensions of code reading • Structure • Domain • Concepts • Context 💔
33. Structure Code is not read linearly
34. Domain • Behavior • Data
35. Concepts
36. Context
37. Reading Code The bigger picture
38. Understanding a new code base • Joining a new team / organisation • Using a new code base
39. Reading Code • What does the code do?
40. Context
41. Reading Code A good place to start: • Check out the code
42. Help in the IDE
43. Help in the IDE • Project structure • Build & run • README • Dependencies • Diagrams
44. Strategies • Identify components • Identify relationships / dependencies • Identify concepts • Gain context
45. A slice of the application
46. Find a starting point
47. Find a starting point • Generic • Main method • Endpoint • Speci fi c • Error message / Exception • Logic / Functionality
48. Help in the IDE
49. Help in the IDE • Search • Navigate
50. Strategies • A particular use case • Draw your own diagrams
51. Reading Code Understanding a piece of code
52. Reading Code • Structured exercises
53. Help in the IDE
54. Help in the IDE • Structure • Hints from your IDE • Tests • Debugging • Refactor for understanding • Context • AI Assistant
56. Strategies • Structured exercises • Memory aids • Dependency graph • State table • Gain context
57. Reading Code What's next?
58. Structured exercises • Code Reading Club: https://codereading.club/ • Code Reading Club Resources: https://github.com/CodeReadingClubs/Resources • The Programmer's Brain - Felienne Hermans
59. Let your tools help you
60. ... and your brain
61. Reading code Slides & More https://maritvandijk.com/presentations/reading-code/