Reading Code Øredev - Nov 10, 2023 https://maritvandijk.com/

Reading Code • We spend more time reading code than writing code

Reading Code We read code when: • adding features • fi xing bugs • understanding a new system • doing code reviews • learning new technologies • etc.

Reading Code "developers on average spend as much as 58% of their time comprehending existing source code" - Felienne Hermans, The Programmer's Brain

Reading Code • We spend more time reading code than writing code • But we don't practice reading code explicitly (much)

Reading Code "How to teach programming (and other things)?" by Felienne Hermans https://www.youtube.com/watch?v=g1ib43q3uXQ

Reading Code • What if we practice reading code explicitly?

Code Reading Club • Code Reading Club https://codereading.club/

Code Reading Club • Printed code • Structured exercises

Examples of exercises • First glance • Identify components & relationships • Most important lines • Identify concepts • Summary

Code Reading Club Learned about ... • reading code • other peoples' perspectives • noticing my own assumptions

Reading Code

Reasons code is confusing 1. Lack of knowledge 2. Lack of information 3. Lack of processing power in the brain

Lack of knowledge • Programming domain • Language / syntax • Programming constructs / algorithms • Business domain • Domain concepts • Business logic

Dealing with a lack of knowledge • Create a list • Research • Memorize

Lack of information • Unknown details • Unfamiliar names • Code connected in unknown ways • Too many things at once

Dealing with lack of information • Chunking

Lack of processing power in the brain • Too many processing steps • Too many variables

Dealing with lack of processing power in the brain • Memory aids • Dependency graph • State table

Dependency graph

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); } } } }

Reading Code Understanding a piece of code

Reading Code • Structured exercises

Dimensions of code reading • Structure • Domain • Concepts • Context

Structure Code is not read linearly

Domain • Behavior • Data

Concepts

Reading Code • Context

Help in the IDE • Structure / Restructure • Domain • Behavior • Syntax highlighting & hints • Context

Strategies • Structure • Identify components & relationships • Identify concepts • Gain context

A slice of the application

Find a starting point

Find a starting point • Generic • Main method • Endpoint • Speci fi c • Error message / Exception • Logic / Functionality

Help in the IDE • Search • Navigate

Strategies • A slice of the application

Reading Code The bigger picture

Understanding a new code base • Joining a new team / organisation • Using a new code base

Reading Code • What does the code do?

Context

Reading Code A good place to start: • Check out the code • See if you can build it

Help in the IDE • README • Project structure • Dependencies • Diagrams

Strategies • Identify components • Identify relationships / dependencies • Identify concepts • Gain context

Reading Code What's next?

Structured exercises • Code Reading Club: https://codereading.club/ • Code Reading Club Resources: https://github.com/CodeReadingClubs/Resources • The Programmer's Brain - Felienne Hermans • Code Reading in Practice - Felienne Hermans & Gien Verschatse

Let your tools help you • Structure/Restructure • Reformat • Refactor • Tests & Debugging • Git history • Search & Navigate • Diagrams • ...

... and your brain

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

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.

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

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.

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.

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.