Reading code - Voxxed Days Bucharest

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