literate programming

<<LITERATE PROGRAMMING>>

Charles AndersonOctober 2016

MOTIVATION

Barney Stinson Motivational Quotes

MOTIVATION

• What does it mean to write a computer program?

• To produce a set of instructions for a computer

• Right?

MOTIVATION

• Who “reads” the program?

• The computer - duh

• Who really reads the program?

MOTIVATION

• Although we write programs to instruct computers, people are the ones who spend the most time reading programs.

• WORM - Write Once - Read Many

LITERATE PROGRAMMING

• “Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want the computer to do.” - Donald Knuth


• An approach to programming that enables the programmer to develop and present programs based on the logic on flow of his/her thoughts

• Rather than what the computer demands

• Writing an essay not a program

KEY FEATURE• Re-ordering the code

• Write in the order of human logic, not the computer

• Top-down, bottom-up, whatever

• Work at the right level of abstraction at the right time - for the human

• Focus on what’s important and defer other things (e.g., error handling)

ANTI-EXAMPLE

Signal-to-noise ratio problem?

public class HelloWorld { public static void main(String[] args) { System.out.println("hello world"); } }

JUST NOISE

$_="krJhruaesrltre c a cnP,ohet";$_.=$1,print$2while s/(..)(.)//;

• Being clever is rarely a good thing, especially for the next Schmoe that comes along next - e.g, Future You


• One source file with two languages:

• Programming language - e.g., Pascal

• Documentation language - e.g., TeX

• The order is based on documentation - author’s idea of how best to present the program


• Two tools to process the input file(s):

• tangle - extract and reorder program

• weave - extract documentation - see example

LITERATE PROGRAMS

• Basic format is:

• document a bit -

• code a bit -

We must include the standard I/O definitions, since we want to send formatted output to stdout and stderr.

<<Header files to include>>= #include <stdio.h> @

LITERATE PROGRAMS

• You can refer to a <<chunk of code>> any time you like.

• No need to declare it

• Add to it

• Refer to its value even before defined

LITERATE PROGRAMS

Here, then, is an overview of the file wc.c that is defined by the noweb program wc.nw: <<*>>= <<Header files to include>> <<Definitions>> <<Global variables>> <<Functions>> <<The main program>> @

ONE WORD

mindovermunch.com

DISCUSSION• Isn’t this just lots of comments? No

• Designed to be read and understood

• Not an afterthought - think before code

• We tried this with JavaDoc, and it failed. No

• “Comments lie” - Bob Martin. LP is still different

DISCUSSION• Some of LP was driven by short-comings of Pascal

• OO improves things, but LP can still help

• AWS CloudFormation JSON

• LP is great for something you come back to

• If you inherit a legacy ball of mud

CONCLUSION

• Literate Programming is an interesting, powerful idea that never quite caught on

• LPers not as bad as Forth programmers

• You might still want to check it out - e.g.,http://www.literateprogramming.com/

literate programming

Software