Literate programming by Donald Knuth

Literate programming is a programming style introduced by Donald Knuth in 1984. The focus is on explaining the logic and reasoning behind a computer program (comments) to human readers, rather than just providing instructions for the computer ( plain source code ).

The key ideas are:

Definition

Literate programming is a programming paradigm where a computer program is explained in natural language interspersed with snippets of macros and traditional source code.

Purpose

Used for reproducible research and open access in scientific computing and data science.

Approach

Literate programming by Donald Knuth Gives programmers templates to develop programs in the order demanded by the logic and flow of their thoughts. Moving away from the manner and order imposed by the compiler.

Interweaving Code and Documentation

Instead of writing code with comments in between, literate programming involves writing the documentation as a narrative explaining the context, with code snippets embedded within the text. The code is organized into small sections or “chunks” that are introduced and explained by the surrounding prose. It supportes very well the locality of behaviour. This makes the program more readable and understandable for humans, which what what we do most of the time – reading and understanding the code.

Prioritizing Human Readability

The primary goal is to create programs that are comprehensible to humans readers, rather than just being executable by a computer. The code is presented in an order that facilitates understanding, rather than the order required by the compiler. The programmer acts as an writer / essayist explaining the concepts and rationale behind the code.

Tangling and Weaving

Literate programming tools are used to generate a “tangle” the code snippets from the literate source file into a compilable program, and to “weave” the narrative text and code into readable documentation. Often with features like cross-references, diagrams, and tables of contents.

Benefits and Drawbacks

Proponents argument that literate programming leads to higher-quality programs, better documentation, and easier maintenance, as the code is thoroughly explained and organized for human comprehension.

You read to understand not to figure it out 🙂

Critics might argue that it adds overhead and complexity, and that well-written code can be self-documenting. Uncle Bob would NOT approve. To sum up literate programming is a paradigm that prioritizes human understanding of programs by interweaving code and documentation into a single narrative source, using specialized tools to extract the executable code and formatted documentation

Literate programming example – Bubble Sort Algorithm

The bubble sort algorithm is a simple sorting algorithm that repeatedly swaps adjacent elements if they are in the wrong order, “bubbling” the largest elements up to the end of the array. It works by iterating through the array, comparing adjacent elements, and swapping them if they are in the wrong order.

Pseudocode

bubbleSort(array)
  for i <- 1 to indexOfLastUnsortedElement-1
    if leftElement > rightElement
      swap leftElement and rightElement
end bubbleSort

// Import the Arrays utility class for printing the array
import java.util.Arrays;

class BubbleSort {

  /**
   * The bubbleSort method implements the bubble sort algorithm
   * to sort an integer array in ascending order.
   *
   * @param array the array to be sorted
   */
  static void bubbleSort(int[] array) {
    int size = array.length; // Get the size of the array

    // Outer loop iterates over the array from the first to the second-last element
    for (int i = 0; i < size - 1; i++) {

      // Inner loop iterates over the unsorted portion of the array
      for (int j = 0; j < size - i - 1; j++) {

        // Compare adjacent elements and swap them if they are in the wrong order
        if (array[j] > array[j + 1]) {
          int temp = array[j]; // Store the larger element temporarily
          array[j] = array[j + 1]; // Swap the elements
          array[j + 1] = temp;
        }
      }
    }
  }

  /**
   * The main method to test the bubbleSort method.
   *
   * @param args command-line arguments (not used)
   */
  public static void main(String[] args) {
    int[] data = {5, 3, 4, 1, 2}; // Create an unsorted array

    System.out.println("Array before sorting: " + Arrays.toString(data));

    bubbleSort(data); // Call the bubbleSort method to sort the array

    System.out.println("Array after sorting: " + Arrays.toString(data));
  }
}