This is a brief introduction to Literate Programming that I presented to our local meet-up, Hack Salem, in October 2016.

1. <<LITERATE
PROGRAMMING>>
Charles Anderson
October 2016

2. MOTIVATION
Barney Stinson Motivational Quotes

3. MOTIVATION
• What does it mean to write a computer program?
• To produce a set of instructions for a computer
• Right?

4. MOTIVATION
• Who “reads” the program?
• The computer - duh
• Who really reads the program?

5. MOTIVATION
• Although we write programs to instruct
computers, people are the ones who spend the
most time reading programs.
• WORM - Write Once - Read Many

6. 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

7. LITERATE PROGRAMMING
• 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

8. 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)

9. ANTI-EXAMPLE
Signal-to-noise ratio problem?
public class HelloWorld
{
public static void main(String[] args)
{
System.out.println("hello world");
}
}

10. 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,
FutureYou

11. LITERATE PROGRAMMING
• 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

12. LITERATE PROGRAMMING
• Two tools to process the input
file(s):
• tangle - extract and reorder
program
• weave - extract
documentation - see example

13. 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>
@

14. 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

15. 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>>
@

16. ONE WORD
mindovermunch.com

17. 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

18. 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

19. 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/