ARTICLE

The Act of Writing Code

From The Programmer’s Brain by Felienne Hermans

6 min readMar 4, 2022

When you program, there are a lot of different types of things that you might be doing. In this article we dive into these different activities that you perform as you program.

Take 35% off The Programmer’s Brain by entering fcchermans into the discount code box at checkout at manning.com.

Different activities while programming

The idea of the different activities that we perform as we program was first described by British researchers Thomas Green, Alan Blackwell and Marian Petre. CDN is a framework to evaluate the cognitive impact of a programming language or code base. CDN also describes five activities: searching, comprehension, transcription, exploration and incrementation.

Figure 1 provides an overview of the five programming activities, what programming tasks you likely do in these activities and what makes each activity hard.

Figure 1 An overview of programming activities and the memory systems they use most

Searching

Searching in code is the activity where you look through a code base, searching for a specific piece of information. This can be the precise location of a bug that you need to address, all calls of a certain method, or the location in which a variable should be initialized.

While searching, you mainly read code and execute code, potentially using breakpoints and a debugger, or replying on print statements as you execute the code. The activity of searching is mainly hard on your short-term memory. You have to remember what you were searching for, what paths in the code you already explored and why, and what you still need to explore in more depth. Therefore, the activity of searching for code is best supported by making notes to offload some of the memories to paper, or to a separate document on your code. Write down what information you’re looking for, where you’ll search next, and what you already found.

It can sometimes be beneficial to make temporary changes to code to ease a certain task. In case of searching within code, it can help a lot if you leave little “breadcrumbs” for yourself in comments indicating why you visited the code. For example, a comment like ## I read this method because I thought it might be involved in the initialization of the page class can help you when you visit the code later on in the same search. This matters when you suspect you might not be able to finish the search in one go, because a meeting or the end of the working day is approaching. Writing down the steps of the search helps you finish it at a later time.

Comprehension

When you perform the activity of comprehension, you read and execute code to gain an understanding of its functionality. It’s similar to searching, but with comprehending you lack a good understanding of what the code does in detail. This can be caused because it is code you wrote a long time ago, or because someone else wrote the code.

Developers, on average, spend as much as fifty-eight percent of their time on comprehending existing source code, and this activity is pretty common in your day-to-day life.

In addition to reading and executing code, comprehension can also include running test code to gain a better understanding of the way the code is intended to work. Comprehension can also include executing refactorings to make the code easier for you to understand.

Refactoring code to be in a form which is easier for you to recognize it helps, because comprehension is an activity which is mainly heavy on your working memory. You need to reason about code that you don’t fully understand yet. As such, supporting the working memory is the best strategy you have when you perform the activity of comprehension. This can be done by refactoring code, but also to make the mental models that you use explicitly. Try to draw a model of the code, and update it each time you learn new information. This way, instead of retrieving information from your brain, you can retrieve it from an external source, which is easier, and having a model at hand can also help to detect misconceptions that you might hold about the code. Also, should you have to finish the task of comprehension at a later time, all notes and drawing that you made can help you to get back into the task with more ease.

Transcription

Transcription is the activity where you “just code”. You have a concrete plan of what you want to add or change to the code base, and you’re going to do that. In its most pure form, in transcribing you’re only coding and nothing else.

Transcription is mainly hard on the long-term memory, because you need to be able to recall syntactic constructions to implement.

Incrementation

Incrementation is a mix of all of the above. When you increment a code base, you’re adding a new feature, which is likely to include both searching for the location(s) to add code, comprehending the existing code to understand where to add code, and how to do that, followed by the transcription of the idea into syntax.

Because incrementation is a mix of activities, it can also be hard on all three memory systems. As such, incrementation tasks, which are the most common tasks in a professional programmer’s life, are in most need of support for the memory systems in the form of notes and refactoring for comprehension.

It depends on your personal experience with the programming language and code base at hand which system is most heavily impacted. If you know the programming language well, your long-term memory might not work hard to remember syntax. On the other hand, if you know the code base well, your working memory and short-term memory might not be impacted by searching and comprehending the code.

If either the code base or the language (or both) is less familiar, incrementation can be a hard task. Where possible, try to split the task of incrementation into separate smaller tasks. Being deliberate about what subtask you do can help you to support the right memory system. Tell yourself that you’ll start by searching for the relevant information, then comprehending it, followed by adding the needed code.

Exploration

The final activity that Green, Blackwell and Petre discuss is exploring code. When you perform the activity of exploration, you’re in essence sketching with code. You might have a vague idea of where you want to go, but by the act of programming you gain clarity about the domain of the problem and about the programming constructs that you need to use.

As in incrementation, when exploring you’re probably performing a number of different programming related tasks in quick succession: writing code, executing the code and running tests to see if you’re going in the right direction, reading existing code and potentially also refactoring code to make it more in line with your newly found plans for the code.

While exploring, it’s likely that you heavily rely on tools in the IDE, for example running tests to see if small changes have impacted any tests, using automated refactoring tools, or relying on “find dependents” to quickly navigate code.

Because exploration too relies on different activities, it’s hard on all three memory systems, but particularly on the working memory, because you make plans and designs on the fly, and also programming. Although you might feel that documenting your plans disrupts your flow and slows you down, it can be helpful to make some rough notes of your design direction or design decisions to free up mental space to think about the problem in more depth.

What about debugging?

When discussing this framework with developers, they often wonder why the activity of debugging is missing from the framework. The answer to this is that when you debug, you often engage in all five of the different activities. Debugging entails fixing a bug, but it often also includes finding the location of the bug before you can fix it.

Therefore, debugging is often a sequence of exploration, searching, and comprehension, followed by writing code. Debugging can often be described as a mix of the five activities.

Exercise 1

During your next coding session, reflect on the five activities of the Cognitive Dimensions of Notation framework. What activity are you performing most of the time? What barriers did you encounter as you searched, comprehended, transcribed, incremented and explored?