This report presents a novel intellectual challenge: the problem of writing a self-documenting program. It then attempts to solve this problem, bringing to light along the way a series of pitfalls and curiosities that underlie our understanding of context and meaning within formal systems such as computer languages. It demonstrates that the problem of self-documenting code probes at the core of questions about self-reference and the use/mention distinction.
As this report deals with issues relating to programming languages in general and C in particular, the reader is assumed to have at least a basic understanding of computer programming. Some experience with various languages, especially C, would certainly be an asset. Since the report examines the problem from the point of view of computer languages, knowledge of specific hardware platforms and operating systems is not required. However, it should be possible for the novice programmer or non-programmer to follow the main arguments presented here.
The body of this report contains six main sections. The first and second sections introduce the concepts of self-reference and self-documenting programs. They set the stage for the challenge by defining the key concepts and showing why the problem of writing a self-documenting program is non-trivial. The next three sections build up from initial attempts at self-documenting programs that fail to more sophisticated attempts that still fail, to actual working programs. At each step, a discussion of the attempt shows what needs to be revised or improved to proceed onward. The final section shows how we can stretch our initial definition of a self-documenting program to produce solutions that seem unsatisfying, and how we can appropriately modify the definition.
Throughout the report, the reader will find terms or phrases which are italicized and underlined, like this. This indicates that the word could be unfamiliar to the reader, and that a short explanation is given in the glossary, which appears at the end of the report. Clicking on that word will take the reader directly to that explanation.
Pieces of C source code appear throughout the report. In some cases, lines of source
were too long to fit on a single line. In these cases, a bold ampersand
&' has been used to indicate that in the source code, the line
containing the ampersand and the line immediately following it should be concatenated
and treated as a single line.