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