Speed code-reading

#books #review #programming

This is the second post in my book review series of The Programmer's Brain by Felienne Hermans. The main point of this chapter is why code-reading is hard and how to speed-code in programming.

Normally, developers spend 60% of our time on average reading code than writing it. Yet, we rarely receive training on how to read code effectively, making this task seems harder than it needs to be. In my opinion, having the ability to read and analyse code written by other developers greatly enhances one's productivity.

Let's have a look at the example below, which is taken from the second chapter of the before mentioned book.

public class InsertionSort {
  public static void main (String [] args) {
    int [] array = {45,12,85,32,89,39,69,44,42,1,6,8};
    int temp;
    for (int i = 1; i < array.length; i++) {
      for (int j = i; j > 0; j--) {
        if (array[j] < array [j - 1]) {
          temp = array[j];
          array[j] = array[j - 1];
                        array[j - 1] = temp;
        }
      }
    }
    for (int i = 0; i < array.length; i++) {
      System.out.println(array[i]);
    }
  }
}

When you read the code snippet above, your brain engages in combining the knowledge stored in your long-term memory (LTM). If you're already familiar with the syntax of a for-loop or an array in Java, you can quickly recall that information.

Additionally, as you read the code snippet, your brain tries to retain key details like the array declaration with elements, the introduction of a temporary variable, the presence of a nested loop to iterate over the same array, and more. It may also recognise that this code implements the Insertion Sort algorithm, which can be a significant time-saver for those who have previously encountered it.


Felienne Hermans, 2.1.1 What just happened in your brain

Why code-reading is hard

Remembering a codebase you've never encountered before is akin to trying to recall the phone number of someone you've just met. It's not an easy task. When we try to remember something, we initially rely on our STM before transferring it to LTM. However, our STM has limited capacity (remember the RAM example?), making it challenging to retain large amounts of new information. Thus, to overcome this limit, our brain needs to collaborate with the LTM.

How to speed-code

To overcome the capacity limit of our STM, we can utilise a technique known as code chunking along with our knowledge of the programming language used in the code we are reading.

In essence, code chunking, also referred to as code grouping or code segmentation, is a programming technique that involves breaking down extensive code sections into smaller, more manageable chunks. These chunks are organised into logical sections or modules based on their functionality, purpose, or organisation.

Since code-chunking helps to read code better, we can then look at how to write chunkable code. One of the methods to help create chunkable code is by using design patterns. This refers to the general, reusable solutions and proven approaches to commonly occurring problems in software design. These patterns facilitate code comprehension by establishing a common language, providing problem-solving guidelines, organising code structures, promoting code reuse, and documenting design intent. By utilising design patterns, developers can more easily grasp the purpose, functionality, and structure of the codebase, leading to improved code comprehension.

Another method is to use comments. While it's true that code should ideally be self-explanatory, comments can be helpful in aiding code comprehension, particularly for novice programmers like myself. High-level comments can provide valuable insights into the codebase and assist in understanding its functionality.

Hermans also mentions another technique called leaving beacons. According to her:

Beacons typically indicate that a piece of code contains certain data structures, algorithms, or approaches.

class Node:                    # this is a beacon
    def __init__(self, key): 
        self.left = None       # this is another beacon
        self.right = None      # this is also a beacon
        self.val = key

In the given code snippet, thanks to these beacons we know that we have a class called Node that represents a node in a binary tree. Each node contains a value and references to its left and right nodes.

In summary, this chapter highlights the importance of effective code reading and presents techniques such as code chunking, comments, and leaving beacons to improve code comprehension. It offers valuable insights for both novice and experienced programmers, making it an interesting and informative read.