What are you, dear comment?

I like the definition of a comment in Markus Krajewski’s text Kulturtechnik Programmieren, as it is close to how I feel about it. He talks about the two layers of code. The first layer is the instructions, which are executed by the machine. This is the actual code or text written in a programming language. The second layer is marked text that is not executed. This piece of text is ignored by the machine.⁠² It can be text, code, a mix, or something like ASCII art. Either way, it does not matter to the machine but to us as readers. To make a comment or mark text so it will not be executed, you will have to use a specific string of symbols to let the program know what follows will be a comment. Here is a small example with HTML.⁠³

<p> This is a tag used in HTML to define a paragraph of text. What follows below is a comment</p> <!-- In HTML, you use this combination of symbols to declare a comment. Everything inside here will not show up when you normally view a website. --> There are two ways to format a comment: block and inline. A block comment is comparable to a paragraph of text with one or multiple line breaks. This would be used for a longer comment. Compared to this, an inline comment is shorter and spans only one line. Here is a quick example of those two types of comments. <p>dear reader</p> <!-- What follows is an inline comment in the same line--> <!-- After this inline comment, I’m currently writing a longer block comment. It spans more than one line of code and has a line break. In the case of HTML, it can be a bit confusing because there is no difference in the symbols used to signify whether it’s an inline or a block comment. -->

This can be handled differently depending on the programming language. There is a lot of variation in the different symbol strings that mark a comment.⁠⁴ For the programming languages I’m familiar with they are as follows:

• HTML uses this <!-- comment --> for both inline and block comments.

• CSS uses this /* comment */ also for both inline and block comments.

• JavaScript and PHP both use //comment for inline comments and /* comment */ for block comments.

Either way, even though the way to mark a text as a comment differs for many programming languages, the functions stay the same. The one I want to focus on is communicating something that is intended for human readers.⁠⁵ As something that seems trivial but has been picked up repeatedly by different authors, the code has a certain duality to it.⁶ It is read by humans as well as machines. More specifically, it is a text read by humans and performed⁠⁷ by machines. This raises the question of who we are writing code for: machine or human? It may seem like we are writing code for the machine to tell it what to do, but are we really? I like how Vikram Chandra puts Donald Knuth’s struggle with this question in Geek Sublime.

If ever there was a person who fluently spoke the native idiom of machines, it is Knuth, computing’s great living sage. More than anyone else, he understands the paradox that programmers write code for other humans, not for machines: “Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. ⁸

Knuth, a big proponent of writing code meant to be read and understood by humans, coined the term literate programming in his 1984 paper and later, in 1992, wrote a book about it. In his case, he advocated for code as a form of discourse between people—the coder as writer and essayist. For Knuth, code should be clear, legible, and communicate its function. Additionally, all the code should be documented in a way that explains how exactly the code works in an elaborate literary way.⁹ He suggests writing code so that big parts of the code are only important to the human reader, not the performing machine. An excerpt from Ross Williams sums this up nicely on Daniel Mall’s website literateprogramming.com.

A traditional computer program consists of a text file containing program code. Scattered in amongst the program code are comments which describe the various parts of the code. In literate programming the emphasis is reversed. Instead of writing code containing documentation, the literate programmer writes documentation containing code.¹⁰

The focus is on the human. The comment is one way to achieve this programming paradigm, as it has a singular human audience. Knuth went down his own rabbit hole with this and created a whole system to program this way.¹¹ This also questions the important part of the code—for Knuth, it’s the comment or the documentation. Similarly, certain currents in literary studies, such as Critical Code Studies or Source Code Criticism, also question this topic. While Critical Code Studies focus more on the meaning and implications of code in terms of the social context,¹² Source Code Criticism is more about developing and generating an understanding of code by enriching the code with knowledge about its origin, function and context.¹³ Bajohr and Krajewski’s take on Source Code Criticism is that the comment is a central tool for documenting and explaining code for further study without interrupting the aspect of the machine performing the code.¹⁴ This way of thinking about the relation between code and comment really resonates with me. Going into this text, I had some of my own ideas about the relation between code and comment, and it’s always nice to realize there were others before me who also thought about this. Everything is so relational—Code or writing, it always happens on the back of others who came before me. Quoting other writing, copying code others have written, writing notes, and writing comments. While writing this text, there is a multitude of different annotations, like my personal notes, all the comments, and footnotes. I’m wondering what the important part is—my writing, personal anecdotes, or the original texts of others I refer to in the footnotes, with this text being a kind of fluff piece to contain them. What is the central or essential part of the writing, and what should be highlighted?

Approaching this from the position of a graphic designer, there is also always a decision to be made about the importance of the running text and everything adjacent to it. What are the relations between the font sizes, how much space will I give footnotes on a page, will they be part of the margin or the running text, and how big will I make the margin? Thinking about the aesthetics of the very traditional ways of book setting from the Middle Ages or the more modern formalized constructions of the print area from the likes of Jan Tschichold, they seem to me like there is an emphasis on big margins.

Apart from the arguments on aesthetics, there is plenty of space for notes. To me, these gestures emphasize commenting, taking notes, or writing your own thoughts in a book that has the physical space for it.¹⁵ In short, there is a lot of space for marginalia—all the sorts of things that are happening in the margins of a book.¹⁶ I like that marginalia are a somewhat open space for what they can be. Everything that happens in the margins or outside of the print area is available for anyone—a sort of free commons on the book page. This feeling does not translate one-to-one for me when going from writing to coding—or a text editor to a coding environment. All of these thoughts of footnotes, quotes, annotations, and marginalia meld together into a comment—or more like they all exist in the space between the opening and closing string of a comment. Although I included marginalia into this space, that is, the comment out of all of the forms of different annotations, marginalia feels closest to comments in terms of openness—as comments, as well as marginalia, can be pretty open spaces in terms of what happens inside them. This also brings me to the title of this thesis Code Marginalia. For me, marginalia serves primarily as a lens through which to view comments, to figure out what they are, how to approach them, and how to connect them to other forms of annotation. This title and topic are also in relation to the ongoing research Kim Kleinert and Polina Lobanova about Marginalia on the Web.

To better understand where comments are coming from, I would like to take a closer look at the history of comments and coding in general. But I also want to take a short detour and glance at the history of marginalia.