Reading code can be confusing in many ways; we are not explicitly taught how to read code, and we rarely practice code reading. Being aware of the cognitive processes that play a role can help to become better at reading code.
Felienne Hermans, associate professor at Leiden University, gave a keynote about the programmer’s brain at QCon Plus November 2021.
Research shows that programmers spend about 60% of their time reading code, but it is still an activity that many programmers find really hard, Hermans said. Knowing what happens in your brain when we read code can help us to understand why it is hard, and how to get better at it.
Hermans distinguished three different processes in the brain that play a role when reading code, or in fact when processing any kind of information: short-term memory(STM), long-term memory, and working memory(WM):
Your long-term memory stores all things you know about programming and about the world. Facts like "javascript use curly brackets to mark blocks", "counting starts at 0 in most programming languages" and "you can search through an array of size n in time log(n)" are stored in the long-term memory. Your short-term memory is more like a buffer that briefly stores information that you see or hear. Finally, your working memory is used to process information.
The most important thing to know about these three memory systems is that your short-term memory and working memory are highly dependent on your long-term memory, Hermans argued:
Consider you reading these sentences; that is easy to do because you know all the letters and almost all of the words. In another language, reading is a very different experience!
In programming we often have this belief that you do not need to know all that much syntax, but in fact, syntax, concepts and domain words can be really confusing if your long-term memory has not stored them, Hermans mentioned. For example, if you are unaware of the meaning of domain concepts, even "clean code" can look confusing, she said.
InfoQ interviewed Felienne Hermans about the challenges of reading code and how to get better at it.
InfoQ: You mentioned that different forms of confusion can happen. Can you elaborate?
Felienne Hermans: Each of the memory systems comes with its own confusion. For example, if you simply do not know a certain keyword, it is your long-term memory that needs help. But if code is structured in a very unfamiliar form, your short-term memory might be overloaded; again you can compare this to reading text in an unfamiliar language. You know how to read, and you might recognize the letters but you will have to translate each word for the sentence to make sense. Finally the working memory can get confused by complex code in which many things happen at the same time.
InfoQ: How can we practice our skills for reading code?
Hermans: The three memory systems that we described above all have their own methods of being strengthened. For long-term memory, a lot of practice of important syntax elements, domain and programming concepts will be very useful, for example using flashcards. To create flashcards you put something familiar on one side of a card and something new on the other side and you practice until you know everything well.
To help your working memory, you can offload some of the processing power outside of your brain, for example using diagrams or annotations.
Finally, short-term memory can be supported with a process I call cognitive refactoring. That is a refactoring done for the benefit of personal understanding, rather than improvement of an existing code base.
InfoQ: What would such a cognitive refactoring look like?
Hermans: An example of a cognitive refactoring is transforming a ternary operation.
Many languages support ternary operators, which are a shorthand for if statements. They typically have the form of a condition followed by the results when the condition is true and then the result when the condition is false, as in this JavaScript example, checking whether the Boolean variable isMember is true:
isMember ? ’$2.00’ : ’$10.00’Some languages support ternary operations in a different order, namely first the value when true, followed by the condition and then the result when the condition is false. An example of such a language is Python, as shown below.
’$2.00’ if is_member else ’$10.00’As above in the JavaScript example, when member is true the ternary operator returns
$2.00, if it is false, $10.00 is returned.Conceptually a ternary operator is not hard to understand; as a professional programmer you are of course familiar with conditional code. However, the fact that the operation is placed on one line, or the fact that the order of the arguments is different from a traditional if statement, might cause the code to create too much mental effort for you. In such a case, a cognitive refactoring of a ternary into a more traditional if-statement can be helpful.
InfoQ: What’s your advice for becoming a better programmer?
Hermans: Read code deliberately. Whether that is in a code review, or in a code reading club, deliberate practice makes perfect! In The Programmer’s Brain I describe several exercises you can use for deliberate code reading, for example writing a summary of a code snippet, or examining the variables in detail.