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/
2. Reading Code Introduction • We spend more time reading code than writing code
3. Reading Code Introduction We read code when: • adding features • fi xing bugs • understanding a new system • doing code reviews • learning new technologies • etc.
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
5. Reading Code Introduction • We spend more time reading code than writing code • But we don't practice reading code explicitly (much)
6. Reading Code Introduction "How to teach programming (and other things)?" by Felienne Hermans https://www.youtube.com/watch?v=g1ib43q3uXQ
7. Reading Code Introduction • What if we practice reading code explicitly?
8. Reading Code Introduction • Code Reading Club https://codereading.club/
9. Reading Code Introduction • Printed code • Structured exercises
10. Reading Code Introduction • So many insights!
11. Reading Code Introduction • But what about the IDE?
12. Reading Code Introduction
13. Reading Code Introduction Code can be confusing because of • Lack of knowledge • Lack of information • Lack of processing power in the brain
14. Reading Code Introduction Lack of knowledge • Business domain • Programming domain
15. Reading Code Introduction Dealing with a lack of knowledge • Create a list • Research • Study
16. Reading Code Introduction Lack of information • Unknown details • Unfamiliar names • Code connected in unknown ways • Too many things at once
17. Reading Code Introduction Dealing with lack of information • Chunking
18. Reading Code Introduction Lack of processing power in the brain • Overwhelmed
19. Reading Code Introduction Dealing with lack of processing power in the brain • Memory aids • Dependency graph • State table
20. Reading Code Introduction Dependency graph
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
22. Reading Code Understanding a piece of code
23. Reading Code Understanding a piece of code • Structured exercises
24. Reading Code Understanding a piece of code Examples of exercises • First glance • Identify components & relationships • Most important lines • Identify concepts • Summary
25. Code reading exercise Code Structure: Roles of variables • (20 min) Together - Discuss the roles of variables
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
27. Reading Code Understanding a piece of code • Syntax
28. Reading Code Understanding a piece of code • Structure
29. Reading Code Understanding a piece of code • Restructure
30. Reading Code Understanding a piece of code • Behavior
31. Reading Code Understanding a piece of code • Context
32. Demo time: Understanding a piece of code
33. Syntax highlighting & other hints Structure / Restructure Behavior Context
34. Reading Code A slice of the application
35. Reading Code A slice of the application • Find a starting point
36. Reading Code A slice of the application • Find a starting point • Generic • Main method • Endpoint • Speci fi c • Error message / Exception • Logic / Functionality
37. Reading Code A slice of the application • Search
38. Reading Code A slice of the application • Navigate
39. Demo time: A slice of code
40. Find a starting point Search Navigate
41. Reading Code The bigger picture
42. Reading Code The bigger picture • Onboarding to a new team / code base
43. Reading Code The bigger picture • What does the code do?
44. Reading Code Introduction A good place to start: • Check out the code • See if you can build it
45. Reading Code The bigger picture • What is the context?
46. Reading Code The bigger picture Strategies: • Identify components • Identify relationships / dependencies • Identify concepts
47. Demo time: The big picture
48. README Project structure Dependencies Diagrams
49. Reading Code Next steps • What's next?
50. Reading code Slides & More https://maritvandijk.com/presentations/reading-code/
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.
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
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.
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.
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.