What is Literate Programming?
Literal Programming is a programming paradigm in which the emphasis on code and comments are reversed. While comments are secondary in most programming languages, and need to be marked as such; in literal programming every line is a comment unless it is marked as code.
What is the Bird style?
Bird style, developed by Richard Bird, is a style of literate programming that is particularly easy to get started with. The formatting is very simple, and it should be pretty obvious to readers even without editor support.
While it lacks some advanced functionality found in other Literate Programming systems, the ease-of-use should reduce friction when introducing it to other people.
Here’s a small example.
Flipping a coin
===============
A coin flip results in either head or tails. Since it is a random process, we
can use the random module.
> import random
Let's define a simple function that returns the result of a coin flip.
> def flip():
> return random.choice(["Heads", "Tails"])
Syntax of the Bird Style
- All lines starting with
>are interpreted as code. - Everything else is a comment.
- Leave a blank line before and after code blocks.
Aside from these rules, you can format your documentation and code in any way.
How to turn it into code?
Due to the simple formatting of the Bird style, it is very easy to convert it to code. It can probably be done using grep or sed.
If you would like a standalone tool that enforces the style a little better, you can use unbird to do this.