On Documentation

On Documentation

Two concepts of “documentation”

The text of the code, written in a programming language (not including comments). This counts as documentation only insofar as it uses natural-language-like names for functions, ops, data, etc. As code, such names have no intrinsic meaning; what meaning they have is strictly computational, determined by the purely syntactic rules of the programming language. The code text expresses (specifies, determines, encodes, etc., but not describes) an algorithm. But insofar as such names borrow from natural language, they also convey a sense or intensional meaning. Unfortunately there is no way to ensure that the intensional (NL) and extensional (computational) meanings align. It follows that the NL sense of the code cannot be fully trusted; in this it is like any documentation (you can call a factorial function “fibonacci”). Natural language text about the code, and/or about the algorithm. I.e. meta-code. In general the task of this sort of documentation is to describe the code/algorithm, rather than express or specify it. On the other hand, documentation might include a piece of text that expresses the algorithm, written in, say, a formal specification language.

[NB: does code describe algorithm? That doesn’t sound right; in some sense the code “is” the algorithm. But that doesn’t sound quite right either. Maybe the best way to put it is that the code encodes the algorithm (hence “code”). But what is the precise nature of this concept of “encoding”? Isn’t it just circular to say that code encodes algorithm? Better yet: code expresses algorithm.]

Expressivity: code expresses algorithms: what exactly does this mean? What is the precise nature of the relation between code and algorithm? This takes us into deep philosophical waters - e.g. what is an algorithm, anyway? Do algorithms have a form? What’s the difference between an algorithm and a process? Etc.

Laws v. Norms

The expression of an algorithm in code involves a relation of necessity: the algorithm you get when you run the code is necessarily the “same” as what the code expresses. The algorithm cannot deviate from the (meaning of the) code text.

By contrast, NL meta-documentation answers to the code as a norm. The meanings expressed by the NL documentation can (and usually do, alas) deviate from the meaning of the code text.

In other words, from the machine perspective, code expresses a law. From the documentation perspective, code expresses a norm.

Learning

How can we discover or learn the meaning of a piece of code? There are two sources of “evidence” as to the meaning of a program: a) the code itself; and b) the behavior of the code, as manifested in a trace from running it.

So one way to support easy discoverability would be to support a “minimal semantic demonstration” (MSD) of the code. This would amount to a specialized variety of unit test. Invoking MSD on a function would result in a display of the form “input -> output” which would demonstrate the semantics in action. For example:

(msd ‘factorial)
-- MSD:  factorial
    (factorial 0) -> 1
    (factorial 1) -> 1
    (factorial 2) -> 2
    (factorial 3) -> 6
    (factorial 4) -> 24

Implementing this as a kind of unit test would serve both as a minimal QA device and as a discovery device.