Literate Programming

The primary goal of literate programming is to create well documented code. Accordingly, a literate programmer simultaneously authors both the documentation and the code. Macros enable both the abstraction and a more intuitive ordering of code. Abstraction is performed primarily to improve understanding, secondarily to foster reuse. Compilation of the documentation (called “weaving”) produces a well formatted TeX document which contains the embedded code as well, ordered in an intuitive fashion. Compilation of the code (called “tangling”) is a single-level process whereby documentation is eliminated, macros are expanded, and the desired code is thereby generated. Macros have similar capabilities and drawbacks of C macros. CWEB, in fact, employs C macros to do much of its work. The primary advantage of literate programming is nicely formatted, readily approachable documentation of the code base.

Literate programming is missing the following components of a Template Oriented Programming (TOP) system:

• Model syntax
• Multi-level model to model translation
• Custom errors to identify model misuse
• Model queries
• Translation debugging

Most of the CWEB manual focuses on formatting of documentation and code, whereas most of a TOP system focuses on model translation. Only the lowest level textual output of a TOP translation focuses on formatting. In a TOP system, the model serves as the documentation. A model pretty-printer can create a well-formatted, hyperlinked, read-only view of the model. Syntax highlighting within a text editor can be employed to create a reasonably formatted writable version of the model.

Literate programming can be a useful way to organize code. It is hoped that a TOP system will provide many of the benefits of literate programming, but also yield a considerably higher return on investment with respect to abstraction. For example, a literate programmer must always be aware of the underlying code being produced. In contrast, a TOP programmer should be able to think at the level of the model being created, for the most part ignoring the translation of that model to lower level model/code.