True source

True source is the method that a programmer used to create a program, which must have included a high degree of comprehension. Anything that transforms source, like a compiler, into something that cannot be comprehended by the same original programmer does not count as true source. It is not the source, as in the place that the code comes from.

This definition comes with an important caveat. True source is not a binary characteristic, but a spectrum. Some sources can be truer than others. This is important because the clearer the code, the more freedom it gives.

Clear freedom

Code that a programmer understood when they wrote it may be incomprehensible to them several months later. People can even understand Befunge, an obfuscated, stack based programming language, during the course of writing it. Such understanding evaporates far more rapidly for Befunge than for most other languages.

Befunge is a deliberate anti-pattern, making the source as incomprehensible as possible. But efforts in the opposite direction are quite rare. Sometimes language designers do consider these things. Guido Van Rossum, for example, deprecated reduce(...) in Python because he believed it led to incomprehensible code. But usually, performance and poor design obviate comprehensibility.

This is unfortunate, because working on the clarity of code is essential to the continued survival of the general purpose computer.

The GNU project, for example, lists the freedom to "study how the program works, and change it so it does your computing as you wish" as software freedom number one. They explain this further by saying that access to source code is a precondition for this freedom, and that what is obfuscated "does not count as source code".

The freedom to "study how the program works" is not well phrased. One can study how a compiled program works by using a decompiler. Anything can be studied as long as it doesn't depend on remote execution, as in a DRM machine. What we need is not code which can be studied, but code which is as comprehensible as possible. We need code which is clear.

When I first learned about GNU/Linux, the promise of an operating system that anybody could learn from, change, and improve was enticing. But I soon learned that if I really wanted to do these things, there were many obstacles. The source was complex, and non-modular. It was difficult to learn, and even if you did learn it, it was difficult to change just a single component without messing up your system—or breaking things that depend on it, which is a separate important problem not discussed here.

Measuring clarity

The clarity of code can be difficult to measure, because the measurement must be manual, not automated. We can count cycles far more easily than we can rate comprehension. Not only that, but when A/B testing code to see if its performance has increased, we can run the test over again on the same hardware. Not so with clarity. Because the performance of people is not constant, unlike with computers, it has to be measured as an average over a group of people. The backgrounds of the people also have to be adjusted for. People who have read the code before also have an advantage in understanding the new code, because they can leverage the understanding that they obtained from the previous version. So you either have to use new people, or compensate for the increased understanding.

The most effective solution to this problem is one that makes this test routine as cheap and efficient as possible. A website where people can volunteer or be paid to review code would be a simple answer. A standard measure of clarity should also be introduced, a kind of readability test for code, like the Flesch, Dale–Chall, or Gunning Fog formulæ for prose.

As with prose, sometimes sophisticated code will be necessary. It depends very much on the concepts being worked on. If the code is intending to run involutions in octonion algebras, then it cannot be of the same level of difficulty as code which performs simple text templating. But difficulty is not to be conflated with clarity. Programmers should strive to create the clearest code which still achieves the chosen task.

Clarity often means that code must be augmented with a lot of prose, and even diagrams and interactive animations. This means that properly designed literate programming is on the opposite end of the spectrum from compiled code, and that regular non-literate (or badly designed literate) programs sit in the middle of this spectrum. Because clarity is an important freedom, this means that properly designed literate programming is more free than any known alternative, and the alternatives should be avoided.