Table of Contents
How we can define code (in sense of computer program, I’m not talking about encryption)? There is more than one answer.
Result of programming #
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
Configuration for a computer #
We can say that code is a configuration for a computer. And we need to define computer:
The computer is a device (software or hardware) that can do computations (see below), which can do some sort of mechanical reasoning (see below).
System of a meaning #
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.
See What Do You Mean? by Kevlin Henney for more explanations.
Forms of a code #
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
- assembly code - typically code without comments
- source code - a lot of code with some comments
- plain text
- markdown - mostly text with a bit of special markup (headers, quotes, etc.)
In the middle (equal amounts of code and text):
Self-explanatory code vs comments #
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.
Some notorious examples of comments in code:
Natural language #
In the beginning, we drew the line between code and text. But this line is pretty thin because we can write code in natural languages (to some extent), for example, inferring SQL queries from plain-text questions about tables.
Text is a portable format, you can easily send it over the internet, you can version it, diff it, etc.
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.
There are alternative approaches, for example:
- we can use tags instead of hierarchies to organize files
- we can use SQL to select files
- 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…
Unpopular opinion: text is actually a really bad medium for storing source code
Editing code in plain text editor (for example, nano, notepad, TextEdit) is a poor experience. To make text editing tolerable we need:
- highlighting (for example, tree-sitter)
- autocomplete (for example, intellisense, langserver, tabnine, kite)
- highlight matching brackets, show lines of indentation, collapse code blocks
- showing contextual documentation with tooltips
- code specific navigation, for example, “jump to definition”
- and other editing specific improvements, like Emmet, parinfer (see history of editors for Lisp).
- “projectional code editing”, for example, tofu
Images in comments #
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.
Visual tools for coding #
We can code with visual representation, for example:
- Scratch - block editor
- Circuitlab - circuit designer
- luna - flow
More examples of beautiful and strange editors:
- The Whole Code Catalog
- Gallery of programmer interfaces
- Visual Programming Languages - Snapshots
- Visual Programming Codex
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. 🚀
People used punch cards to write code and store information in the past:
Image source: wikipedia
Plug boards can be used to “write” code:
Image source: wikipedia