Literate Programming — ELI5

Imagine you are writing a recipe book. You could just list ingredients and oven temperatures with no explanation. Anyone who reads it would know what to do, but not why. Why do you beat the eggs first? Why is the oven set to 180 degrees and not 200? Without the story behind the steps, the recipe is hard to follow.

Literate programming means writing code the same way you would write a story — explanations first, code second. Instead of a computer file full of instructions that only a machine understands, you create a document that a human can read like an essay. The code is woven into the story at the moments where it makes sense.

Donald Knuth, one of the most famous computer scientists ever, invented this idea in 1984. He believed that programs should be written for people to read, not just for machines to run. He built a system where he could write a book and have the computer pull the code out and run it.

In Python, the closest everyday example is a Jupyter notebook. You write a paragraph explaining what you plan to do, then a block of code that does it, then another paragraph about what happened. A reader can follow along like a story.

Why does this matter? Because most of the cost of software is not writing it — it is reading it later. When someone new joins a project and needs to understand thousands of lines of code, a program written as a story is far easier to pick up than a wall of raw instructions.

One thing to remember: Code tells a computer what to do. Literate programming tells a human why.