I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Tim’s talk required some previous knowledge of Donald Knuth. If you don’t know who that is Wikipedia has a good summary. Tim’s background is largely with the Axiom algebra system.
Tim talked about how back in the 1970s you programmed in very small files. Nothing could be more than 4K so you ended up with these trees of tiny bits of code and relied upon build systems to put it all together.
IBM’s standard for documentation requires things to be written at the 8th grade level. This is understandably quite tough when you’re documenting complex algorithms.
Tim knows what code he wrote years ago does. He knows that if he takes it out things will break. The problem is he doesn’t know why he wrote it in the first place. This was tough when he faced the task of working with 1.2 million lines of uncommented code. The 8th-grade level documentation didn’t really help. In the early projects he worked on they didn’t write down the “Why” of code. Turns out that’s really, really important.
Tim sought a technology that would let him capture the “Why” of code. This, essentially, is literate programming and stems from Donald Knuth, the writer of LaTeX, METAFONT, and many more pieces of code. A literate program should pass the Hawaii Test. This is where you take the program, print it in book form, give it to a programmer for a couple weeks, send that person to Hawaii. When they’re back they should be able to work on and modify the original code as well as the original programmer. If you have that, you have a literate program.
The book form of a literate program includes all the necessary source code to build a system along with all the documentation and narration required to understand that system.
Tim argued that programming teams need an Editor in Chief. No one should be able to check in code without this EIC affirming that the code has an explanation along with it. The EIC gets between developers and the repository and says, “We’re writing a book about this code. You can’t check in code without the code and the story about what the code does matching.” When you have the explanation along with code you can compare a programmer’s stated goal with the reality of what the code does.
Companies depend upon pieces of software that former employees created. If you don’t understand that code you end up rewriting it. By ensuring our programs are literate programs we provide for stronger future proof code.