Literate programming is proactive rubberducking
===============================================

A few weeks ago I had an email conversation with Gijs Hillenius [1].
His enthusiasm about literate programming inspired me to have some
hands-on experience with it.

Literate programming
--------------------
In the early eighties, Donald Knuth, the creator of the TeX computer
typesetting system, invented literate programming.

According to Wikipedia [2], implementing literate programming consists
of two steps:

* Weaving: Generating a comprehensive document about the program and
  its maintenance.

* Tangling: Generating machine executable code

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

The Wikipedia page makes the bold statement that "literate programming
tools are used by millions of programmers today". Reading the book
`Coders at Work' [3] gives a more nuanced idea about this. 

Emacs Org-Babel Mode
--------------------
Emacs Org-Babel Mode [4] makes it easy to practice literate
programming.

Just write text in org-mode, which is a wonderful tool for writing.
Incorporate computer code in the org file by writing code blocks. A
code block starts with `#+begin_src', followed by the language of the
code.

This is how a code block looks like:

   #+begin_src emacs-lisp
   (defun hello-world ()
      (message "%s" "Hello world"))
   #+end_src

To execute a code block, press `C-c C-c' (Emacs-speak for Ctrl-c twice).
Any output will be embedded in your org file.

Working this way, you create code snippets and immediately generate
the output from the snippet.

Run the org-babel-tangle command (`C-c C-v t') to export the code from
the snippets to an output file.

Which snippets are tangled depends on the settings.

See for example the following line:

   #+PROPERTY: header-args:emacs-lisp :exports code :results none :tangle ~/output.el

With this line in the heading of your org-file, the tangle command
searches for code blocks with the header `#+begin_src emacs-lisp' and
exports the contents of these blocks to the file `~/output.el'.

Top down and bottom up
----------------------
Outlining is one of the strengths of org-mode. It organizes your document
in a hierarchical structure. Use org-mode for some time, and outlining
becomes a second nature.

When practicing literate programming with org-mode, it's only natural
to start with an outline. Thus you start with a top down approach.

Using code blocks you write small snippets of code, a more
a bottom up approach.

Literate programming benefits the lonely software engineer in the
attic, who works alone on code for personal use with little to no
feedback, by integrating the top down and bottom up perspectives.

Literate programming is proactive rubberducking
-----------------------------------------------
Practicing literate programming this way, mingling prose and code in
an org-file, zooming in and out from the top down view to bottom up
view and back, is having a conversation with oneself.

The usual moment for software engineers to converse with oneself is
during the stage of rubberducking [5].

Conclusion:

      Literate programming is a proactive form of rubberducking.


Happy programming!

 
[1]: https://hillenius.net/
[2]: https://en.wikipedia.org/wiki/Literate_programming
[3]: https://en.wikipedia.org/wiki/Coders_at_Work
[4]: https://orgmode.org/worg/org-contrib/babel/how-to-use-Org-Babel-for-R.html
[5]: https://en.wikipedia.org/wiki/Rubber_duck_debugging


Last edited: $Date: 2024/02/26 10:35:35 $