One way to define code is to say this is the result of programming (along with documentation and tickets). For the fullness of definition we would need to define what is programming:
We define programming, as a general human activity, to mean the act of extending or changing a system’s functionality. Programming is a widespread activity that is done both by nonspecialists (e.g., consumers who change the settings of their alarm clock or cellular phone) and specialists (computer programmers, the audience of this book).
– Concepts, Techniques, and Models of Computer Programming by Peter Van Roy and Seif Haridi
Another way to see code is to interpret it as a system of meaning. If we would say that programming is a way to build knowledge. In the same way, as we turn some common knowledge into science:
first, we gather some observations and ideas,
then we try to organize it in some system,
then we try to understand the essence of the process and propose some model which we can use to do prediction if we are able to predict things we think that we understand the process.
In science mathematical model is the highest form of understanding. In the same sense, code can be thought of as the highest way to understand things, because we can run code and “verify” results.
Let’s assume that the code is some form of a text. On the other hand, not all text is the code, right? Let’s put a line between the code and the “plain” text:
plain text is something written in natural language, for example, documentation and comments
code is something written in a programming language
When we write software we use both. We can use them separately or in the mix. We can think about is as the spectrum (from the plain text to the code):
mostly code mostly text
<-------------------------------------------------------------------------->
assembly literate programming plain text
source code Jupyter Notebook markdown
Mostly code:
assembly code - typically code without comments
source code - a lot of code with some comments
Mostly text:
plain text
markdown - mostly text with a bit of special markup (headers, quotes, etc.)
Some people insist that comments are bad and instead we should use self-explanatory code exclusively. I believe that this is
false dichotomy, we can use both.
There is no empirical evidence that self-explanatory code is easier to debug
Replacing all comments with self-explanatory code can increase code indirection - e.g. bigger number of small functions will force you to jump across code forward and backward. See
this post for explanations.
But I do get the point of people who advocate for self-explanatory code over comments:
comments can get stale (unused code gets stale as well)
comments are not verified by tests or type checkers
I’m just saying there is no need to be extreme about it.
The main cons of text (from my PoV) is a file system (which is not required, but assumed most of the time). File system creates one more level of decisions to be taken - how to structure folders, how to name files. Good frameworks (for example, Rails) remove this issue by providing conventions for naming.
we can use unique file names like in
IFPS (
IPNS is used for human-readable names)
we can use canvas instead of files in directories like in
luna.
AST instead of text, hashes instead of names, no file system:
The fact that things were done a certain way in the 1970s is not a good reason to keep doing them, especially if they make programming worse.
Each Unison definition is some syntax tree, and by hashing this tree in a way that incorporates the hashes of all that definition’s dependencies, we obtain the Unison hash which uniquely identifies that definition.
We’re used to thinking about our codebase as a bag of text files that are mutated as we make changes to our code, but in Unison the codebase is represented as a collection of serialized syntax trees…
I’ve been trying to layout code in a visually pleasing manner lately with lots of diagrams. I’m finding it useful to remember what the code does but also as visual cues to find where things are. It can be a pain to edit though.
I sometimes want to draw pictures in comments. It is possible to use good old ASCII-art, or use special markup (for example,
DOT Language), or inline SVG.
We are not limited to software. People “write” programs with hardware as well, for example:
A (very) early example of video game art… Atari’s Space Race (1973) did not have a ROM to store data. So half of the rocket shape was stored as an 8x16 diode matrix, which was mirrored to create the full shape. This is plainly visible in the schematic and the circuit board. 🚀
