Literate programming
Literate programming is a programming paradigm introduced by Donald Knuth in which a computer program is given an explanation of its logic in a natural language, such as English, interspersed with snippets of macros and traditional source code, from which compilable source code can be generated. The approach is used in scientific computing and in data science routinely for reproducible research and open access purposes. Literate programming tools are used by millions of programmers today. The literate programming paradigm, as conceived by Knuth, represents a move away from writing computer programs in the manner and order imposed by  the computer, and instead enables programmers to develop programs in the order demanded by the logic and flow of their thoughts. Literate programs are written as an uninterrupted exposition of logic in an ordinary human language, much like the text of an essay, in which macros are included to hide abstractions and traditional source code. Literate programming (LP) tools are used to obtain two representations from a literate source file: one suitable for further compilation or execution by a computer, the "tangled" code, and another for viewing as formatted documentation, which is said to be "woven" from the literate source . While the first generation of literate programming tools were computer language-specific, the later ones are language-agnostic and exist above the programming languages. History and philosophy. Literate programming was first introduced by Knuth in 1984. The main intention behind this approach was to treat a program as literature understandable to human beings. This approach was implemented at Stanford University as a part of research on algorithms and digital typography. This implementation was called "WEB" by Knuth since he believed that it was one of the few three-letter words of English that hadn't already been applied to computing . However, it correctly resembles the complicated nature of software delicately pieced together from simple materials. The practice of literate programming has seen an important resurgence in the 2010s with the use of computational notebooks, especially in data science. Concept. Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. Macros in a literate source file are simply title-like or explanatory phrases in a human language that describe human abstractions created while solving the programming problem, and hiding chunks of code or lower-level macros. These macros  are similar to the algorithms in pseudocode typically used in teaching computer science. These arbitrary explanatory phrases become precise new operators, created on the fly by the programmer, forming a "meta-language" on top of the underlying programming language. A preprocessor is used to substitute arbitrary hierarchies, or rather "interconnected 'webs' of macros", to produce the compilable source code with one command ("tangle"), and documentation with another ("weave"). The preprocessor also provides an ability to write out the content of the macros and to add to already created macros in any place in the text of the literate program source  file, thereby disposing of the need to keep in mind the restrictions imposed by traditional programming languages or to interrupt the flow of thought. Advantages. According to Knuth, literate programming provides higher-quality programs, since it forces programmers to explicitly state the thoughts behind the program, making poorly thought-out design decisions more obvious. Knuth also claims that literate programming provides a first-rate documentation system, which is not an add-on, but is grown naturally in the process of exposition of one's thoughts during a program's creation. The resulting documentation allows the author to restart his own  thought processes at any later time, and allows other programmers to understand the construction of the program more easily. This differs from traditional documentation, in which a programmer is presented with source code that follows a compiler-imposed order, and must decipher the thought process behind the program from the code and its associated comments. The meta-language capabilities of literate programming are also claimed to facilitate thinking, giving a higher "bird's eye view" of the code and increasing the number of concepts the mind can successfully retain and process. Applicability of the concept to programming on a large  scale, that of commercial-grade programs, is proven by an edition of TeX code as a literate program. Knuth also claims that literate programming can lead to easy porting of software to multiple environments, and even cites the implementation of TeX as an example. Contrast with documentation generation. Literate programming is very often misunderstood to refer only to formatted documentation produced from a common file with both source code and comments – which is properly called documentation generation – or to voluminous commentaries included with code. This is the converse of literate programming: well-documented code or documentation extracted from code follows  the structure of the code, with documentation embedded in the code; while in literate programming, code is embedded in documentation, with the code following the structure of the documentation. This misconception has led to claims that comment-extraction tools, such as the Perl Plain Old Documentation or Java Javadoc systems, are "literate programming tools". However, because these tools do not implement the "web of abstract concepts" hiding behind the system of natural-language macros, or provide an ability to change the order of the source code from a machine-imposed sequence to one convenient to the human mind, they can not properly be called literate programming tools in the sense intended by Knuth. Critique. In 1986, Jon Bentley asked Knuth to demonstrate the concept of literate programming for his "Programming Pearls" column in the "Communications of the ACM", by writing a program in WEB. Knuth sent him a program for a problem previously discussed in the column (that of sampling "M" random numbers in the range 1.."N"), and also asked for an "assignment". Bentley gave him the problem of finding the "K" most common words from a text file, for which Knuth wrote a WEB program that was published  together with a review by Douglas McIlroy of Bell Labs. McIlroy praised the intricacy of Knuth's solution, his choice of a data structure (a variant of Frank M. Liang's hash trie), and the presentation. He criticized some matters of style, such as the fact that the central idea was described late in the paper, the use of magic constants, and the absence of a diagram to accompany the explanation of the data structure. McIlroy, known for Unix pipelines, also used the review to critique the programming task itself, pointing out that in Unix (developed at Bell Labs), utilities  for text processing (tr, sort, uniq and sed) had been written previously that were "staples", and a solution that was easy to implement, debug and reuse could be obtained by combining these utilities in a six-line shell script. In response, Bentley wrote that: McIlroy later admitted that his critique was unfair, since he criticized Knuth's program on engineering grounds, while Knuth's purpose was only to demonstrate the literate programming technique. In 1987, "Communications of the ACM" published a followup article which illustrated literate programming with a C program that combined artistic approach of Knuth with engineering approach  of McIlroy, with a critique by John Gilbert. Workflow. Implementing literate programming consists of two steps: Weaving and tangling are done on the same source so that they are consistent with each other. Example. A classic example of literate programming is the literate implementation of the standard Unix codice_1 word counting program. Knuth presented a CWEB version of this example in Chapter 12 of his "Literate Programming" book. The same example was later rewritten for the noweb literate programming tool. This example provides a good illustration of the basic elements of literate programming. Creation of macros. The following snippet of  the codice_1 literate program shows how arbitrary descriptive phrases in a natural language are used in a literate program to create macros, which act as new "operators" in the literate programming language, and hide chunks of code or other macros. The mark-up notation consists of double angle brackets ("codice_3") that indicate macros, the "codice_4" symbol which indicates the end of the code section in a noweb file. The "codice_5" symbol stands for the "root", topmost node the literate programming tool will start expanding the web of macros from. Actually, writing out the expanded source code can be done from  any section or subsection (i.e. a piece of code designated as "codice_6", with the equal sign), so one literate program file can contain several files with machine source code. The purpose of wc is to count lines, words, and/or characters in a list of files. The number of lines in a file is .../more explanations/ Here, then, is an overview of the file wc.c that is defined by the noweb program wc.nw: We must include the standard I/O definitions, since we want to send formatted output to stdout and stderr. The unraveling of the chunks can be done in  any place in the literate program text file, not necessarily in the order they are sequenced in the enclosing chunk, but as is demanded by the logic reflected in the explanatory text that envelops the whole program. Program as a web—macros are not just section names. Macros are not the same as "section names" in standard documentation. Literate programming macros can hide any chunk of code behind themselves, and be used inside any low-level machine language operators, often inside logical operators such as "codice_7", "codice_8" or "codice_9". This is illustrated by the following snippet of the codice_1 literate  program. The present chunk, which does the counting, was actually one of the simplest to write. We look at each character and change state if it begins or ends a word. In fact, macros can stand for any arbitrary chunk of code or other macros, and are thus more general than top-down or bottom-up "chunking", or than subsectioning. Knuth says that when he realized this, he began to think of a program as a "web" of various parts. Order of human logic, not that of the compiler. In a noweb literate program besides the free order of their  exposition, the chunks behind macros, once introduced with "codice_11", can be grown later in any place in the file by simply writing "codice_6" and adding more content to it, as the following snippet illustrates ("plus" is added by the document formatter for readability, and is not in the code). If we made these variables local to main, we would have to do this initialization explicitly; however, C globals are automatically zeroed. (Or rather,``statically zeroed." (Get it?) Record of the train of thought. The documentation for a literate program is produced as part of writing the program. Instead of comments provided  as side notes to source code a literate program contains the explanation of concepts on each level, with lower level concepts deferred to their appropriate place, which allows for better communication of thought. The snippets of the literate codice_1 above show how an explanation of the program and its source code are interwoven. Such exposition of ideas creates the flow of thought that is like a literary work. Knuth wrote a "novel" which explains the code of the interactive fiction game Colossal Cave Adventure. Literate programming practices. The first published literate programming environment was WEB, introduced by Knuth in 1981  for his TeX typesetting system; it uses Pascal as its underlying programming language and TeX for typesetting of the documentation. The complete commented TeX source code was published in Knuth's "TeX: The program", volume B of his 5-volume "Computers and Typesetting". Knuth had privately used a literate programming system called DOC as early as 1979. He was inspired by the ideas of Pierre-Arnoul de Marneffe. The free CWEB, written by Knuth and Silvio Levy, is WEB adapted for C and C++, runs on most operating systems and can produce TeX and PDF documentation. There are various other  implementations of the literate programming concept (some of them don't have macros and hence violate the order of human logic principle): Other useful tools include % here text describing the function: fact 0 = 1 fact (n+1) = (n+1) * fact n here more text comp :: (beta -> gamma) -> (alpha -> beta) -> (alpha -> gamma)