Literate Programming

Singapore Clojure Meetup

June 2019

What is It?

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

—Donald E. Knuth

Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

—Donald E. Knuth

Ingredients

Programming language
Documentation formatting language
Toolchain

Ingredients

Programming language: Pascal
Documentation formatting language: Tex
Toolchain: Web

Ingredients

Programming language: Clojure
Documentation formatting language: Markdown
Toolchain: Marginalia

Ingredients

Programming language: Any
Documentation formatting language: Org
Toolchain: Org Babel

New Concepts

\begin{equation} \text{literate programming document} \xrightarrow{\text{tangle}} \text{source code} \end{equation}

\begin{equation} \text{literate programming document} \xrightarrow{\text{weave}} \text{documentation} \end{equation}

Benefits of Literate Programming

Definiteness of purpose
Audience
Great documentation

Case Study: Marginalia

Description

While the phrase ultra-lightweight literate programming is used to describe Marginalia, it is in no way a tool for classical literate programming. That is, Marginalia is a linear documentation generator allowing no out-of-order reassembly of source.

— Marginalia README

Strengths & Weaknesses

Build narrative style documentation from docstrings & comments.
- Docstrings mechanism has improved a lot since the original paper..
lein marg and lein codox can co-exist.
No out-of-order listing of source is a deal breaker for literate programming as a development method.

Weave Looks Like This

Case Study: Org Babel

Shopping List

Emacs
Org Mode
Babel
org-babel-clojure

Org Syntax - Basics

** This is a heading

This is a normal paragraph.

Org Syntax - Code

** Here is a code block:

#+BEGIN_SRC clojure
(defn add [a b]
  (+ a b))
#+END_SRC

Keyboard Driven Interface

C-RET adds a new heading.
M-RET adds a new list item.
M-LEFT promotes heading/list item.
M-RIGHT demotes heading/list item.

Focus & Productivity

< s TAB expands to:

#+BEGIN_SRC █

#+END_SRC

Cursor (█) where you are going to enter the language.

C-c ' switches to a buffer that contains only the contents of the snippet. This buffer has all the right modes set, just as if you have opened and actual file in that language. Then you can C-c ' again to go back to your original document.

Tangling

#+BEGIN_SRC clojure :tangle src/core.clj :mkdirp yes :comments link

#+END_SRC

:tangle specifies the filename this code block needs to be tangled in.
:mkdirp yes instructs tangle to create directories as necessary.
:comments link will surround tangled code with comments that refers back to the original literate programming document. This information can also be used to jump to the source if you are debugging inside Emacs.

Out of Order Definitions

This code block contains a reference to another code block:

#+BEGIN_SRC clojure :noweb yes
  (divide [numerator denumerator]
    <<assert_not_zero>>
    (/ numerator denumerator))
#+END_SRC

#+NAME: assert_not_zero
#+BEGIN_SRC clojure
  (assert (not (zero? denumerator)))  ;; <- hard-coded
#+END_SRC

Org-Babel Tips

In an org document you can mix and match languages if you are executing them within org, not sure if similar thing can be done in babel. C-c C-c to execute.
You can insert the result of a code block instead of its contents (source).
While working with noweb references, C-c C-v C-v creates a (read-only) buffer for the current code block with all the references expanded. Good for syntax checking.

Discussion Points

Comparison with TDD

Literate programming focuses on explaining the why and how.
- Good for experiments and teaching material.
TDD focuses on specifying the behavior
- Good for large scale software development.
Combination is possible and possibly tedious.

Are we trained to ignore comments?

Eclipse

IntelliJ

Visual Studio Code

Emacs

Thank You

Atamert Ölçgen

References

Papers
- Literate Programming by Donald E. Knuth
Technologies mentioned:
Technologies used:
Images: