Konubinix' opinionated web of thoughts

Literate Programming

Fleeting

Considérer le code source comme de la littérature.

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

— https://en.wikipedia.org/wiki/Literate_programming#cite_note-6

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.

— https://en.wikipedia.org/wiki/Literate_programming

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

— https://orgmode.org/worg/org-contrib/babel/intro.html

The Org document can then be exported (woven in LP speak) to HTML or LaTeX for consumption by a human, and the embedded source code can be extracted (tangled in LP speak) into source code files for consumption by a computer.

— https://orgmode.org/worg/org-contrib/babel/intro.html

  • Weaving: Generating a comprehensive document about the program and its maintenance.
  • Tangling: Generating machine executable code

— https://en.wikipedia.org/wiki/Literate_programming

Weaving and tangling are done on the same source so that they are consistent with each other

— https://en.wikipedia.org/wiki/Literate_programming

create programs that were suitable literature for human beings

— https://en.wikipedia.org/wiki/Literate_programming

implementation was called “WEB” since he believed that it was one of the few three-letter words of English that had not yet been applied to computing

— https://en.wikipedia.org/wiki/Literate_programming

Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros.

— https://en.wikipedia.org/wiki/Literate_programming

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.

— https://en.wikipedia.org/wiki/Literate_programming

produce the compilable source code with one command (“tangle”), and documentation with another (“weave”)

— https://en.wikipedia.org/wiki/Literate_programming#cite_note-6

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.

— https://en.wikipedia.org/wiki/Literate_programming#cite_note-6

resulting documentation allows the author to restart their own thought processes at any later time, and allows other programmers to understand the construction of the program more easily

— https://en.wikipedia.org/wiki/Literate_programming#cite_note-6

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

— https://en.wikipedia.org/wiki/Literate_programming#cite_note-6

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

— https://en.wikipedia.org/wiki/Literate_programming#cite_note-6

allows for better communication of thoughts

— https://en.wikipedia.org/wiki/Literate_programming#cite_note-6

tangling

tangling

weaving

backlinks in the tangled document

We often can have backlinks in the source code to easily go back to the document to change its code.

Notes linking here