Recently, I came across some programming advice that I disagreed with. When I thought about why I disagreed with it, I realized that the argument forming in my head followed from my foundational beliefs about code. So I thought it would be a useful exercise to set those thoughts down as clearly as I could. This post is my vehicle for the first part of that exercise.
Please let me know if you think I got anything wrong.
Ready? Let’s go!
What is code?
Code (or source code) is a formal, typically textual document written in a programming language and having two parts: the first part is logic, which instructs a computing device what to do in the language’s syntax and according to the language’s semantics; and the second part is commentary, which communicates important information directly to the code’s audience; the combined purpose of these being to instruct a computing device what to do in a form that is easy for the code’s intended audience to understand and maintain.
What is the purpose of code?
If you disagree with me about what makes for good code (a subject for a later post), the best place to make your assault on my argument is probably going to be in the purpose part of my definition of code, upon which my conclusions rest. To recap:
The purpose of code is to instruct a computing device what to do in a form that is easy for the code’s intended audience to understand and maintain.
Most people will find the first half of my claim uncontroversial: code has the purpose of instructing a computing device what to do. If we want computing devices to do things, we must tell them what to do somehow. Since the “we” in question is generally humans—usually the humans tasked with the creation and maintenance of the code in question—it follows that however we tell the devices what to do, it must be in a form that is easy for this audience to understand and maintain. This is the rationale for the second half of my claim.
Discussion
To clarify my definitions, let’s discuss points that may not be obvious. If you have any questions I haven’t covered, just drop a comment below or send me an email.
What do you mean by the “intended audience” for a work of code?
By “intended audience,” I mean the people (and AI agents) who are expected to read and/or maintain the code over its expected lifecycle. The intended audience for a work can therefore vary markedly, depending on the situation.
In professional settings, the audience is generally assumed to be programmers who are “skilled in the art”: they are competent in the programming languages, libraries, and idioms in use, and they have a working knowledge of their organization’s software development practices. That is, they are expected to have already internalized the common knowledge needed to work effectively within their organizations.
For example, we would expect the intended audience for C++ code at Google to have a working understanding of C++, Google’s C++ Style Guide, and Google’s practices for code reviews and source-code management. This assumption allows C++ code to be written across the company efficiently because it eliminates the burden of having to re-explain these common foundations with each new work of code. These common parts have been “factored out” and placed into the organization’s engineering culture, where all projects can share them.
You say that “code instructs a computing device what to do,” but how does this definition apply to code in declarative languages like Prolog and SQL, where you just supply constraints and let the computer figure out what to do?
I think the definitions work just fine for this case. Recall that code “instructs a computing device what to do in the language’s syntax and according to the language’s semantics.” When you define facts and relations in Prolog and then run a query, for example, the language’s semantics say that you are instructing the computing device to search for a resolution refutation of the negated query. You haven’t supplied a literal series of do-this-do-that instructions, but you are nonetheless instructing the computing device to search on your behalf. The same argument generally applies to other declarative programming languages.