Literate program

The art of good documentation is the art of leaving things out but in a consistent and useful way so that your documents are well structured, concise, and readable. In a sense, our ideal documentation would look like a cross between Knuth s Web of literate programming and a clear structure that separates specifications and external views of things from their internals. 

Knuth84] Knuth, D. 1984. Literate Programming. The Computer Journal, 27(2) ... 

Abstract. In this paper, we advocate the use of literate programming techniques in molecular physics and quantum chemistry. With a suitable choice of publication medium, literate programming allows both a theory and corresponding computer code to be placed in the public domain and subject to the usual open criticism and constructive use which form an essential ingredient of the scientific method. 

The use of literate programming methods leads naturally to structure and standardization in computer code. In turn, this structure leads to subroutine libraries and we describe the specification of a basic tensor algebra subroutine library, which we have recently developed, and which we expect to prove useful in a range of applications. 

We briefly consider the use of literate programming techniques in enhancing collaborative virtual environments, which facilitate developed cooperation between geographically distributed sites. 

In this paper, we advocate the use of literate programming methods, first introduced by Knuth [2], but now little used [3], as a means of placing computer code in the public domain along side the associate theoretical apparatus. Such publication not only places the work in the body of scientific knowledge but also serves to establish authorship. 

D.E. Knuth introduced the concept of literate programming in 1984. He believe[d] that the time [was] ripe for significantly better documentation of programs, and that we [could] best achieve this by considering programs to be works of literate. ... 

Literate programming is a system of programming for the generation of structured and documented programs. As Knuth puts it,... 

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. 

Thus literate programming appears ideally suited to the task of publication in computational molecular physics and quantum chemistry, and indeed, in other computational sciences and in engineering. This task must entail placing both the theoretical model and the associated computer code in the public domain, where they can be subjected to the open criticism and constructive use which forms an integral part of the scientific method. 

Probably the main reason for literate programming failing to survive in the literature is that it imposes its own styles and conventions. ..,... 

The adoption of literate programming methods should lead naturally to structure in a computer program. If we are to consider programs to be works of literature then, just as a book is divided into parts and chapters, and the chapters are further divided into sections and subsections, perhaps supplemented by appendices, the literate approach to programming leads to a modularity of the code. This modularity leads in turn to the concept of a library, a set of fundamental building blocks from which large codes can be synthesized. 

The use of literate programming techniques means that we can clearly indicate contravariant and covariant indices in the IAIj]]X fragment describing code for btas. 

H.M. Quiney and S. Wilson, Literate programming in quantum chemistry A simple example. Intern. J. Quantum Chem. Vol. 104, p. 430(2005). 

In some cells, dmg treatment and other stimuli can trigger a series of complex cytoplasmic biochemical reactions that appear to constitute a cellular suicide program, culminating in the degradation and compaction of chromatin. This programmed mode of cell death is known as apoptosis, and in nomral cellular conditions, it plays a considerable role in the early development of homeostasis of adult tissues. Apoptosis or literally programmed cell death, is so far known to be triggered by three major stimuli cell surface receptors such as FAS, mitochondrial response to stress, and cytotoxic T-cells. 

In the following section, we show that not only does literate programming provide high quality documentation of programs and algorithms but also facilitates their publication. 

Literate Programming. - In his 1968 publication Public Knowledge the Social Dimension of Science, John Ziman answers the question What is Science 1 by asserting that Science is Public KnowledgeHe continues20... 

Knuth made these observations twenty years ago. Yet to date they have had surprising little impact in computational quantum chemistry or, indeed, computational chemistry in general. There is no mention of literate programming methods in, for example, the Encyclopedia of Computational Chemistry,28 a major reference work in the field published in 1998. (A notable exception is the... 

---