Frontier Software

Robert Laing's programing notes

Data-Driven Design

By Robert Laing

Literate Programming

Computer programs are fun to write, and well-written computer programs are fun to read. — Donald Knuth’s opening sentence of Literate Programming published in 1983

Many years ago, I typeset and published a book for a friend by converting her Microsoft Word document into LyX, an open source graphical frontend for LaTeX, which simplified using Knuth’s mathematical typesetting language TeX.

A reason I did this was a large company had blatantly plagiarised material from the ringbound printouts of her MS Word document done by the local business centre. Lawyers got her nowhere. With the aid of LyX, her training manual was turned into a beautifully typeset, bound softback complete with table of content pointing to the correct page numbers, and even an index. As soon as the plagiarists saw it, they assumed she had secured the support of some massive publisher — not just some hobbyest friend publishing it as a learning exercise — admitted guilt and paid royalties. Her sales to students also went up.

TeX is very good at producing files for printers — where the dominant format is Adobe’s PDF, a descendant of PostScript, an implementation of a programming language called Forth.

Principle of least power

Horror stories of how pranksters and criminals abused that “files for printing” were in fact written in a fully-fledged programing language able to do plenty of malicious stuff prompted Tim Berners-Lee to addopt a “principle of least power” for HTML.

I could have used a language like Donald Knuth’s TeX, which though it looks like a markup language is in fact a programming language. It would have allowed very fancy typography and all kinds of gimmicks, but there would have been little chance of turning web pages into anything else. — Weaving the Web: The Past, Present and Future of the World Wide Web by its inventor, published in 2000

Efforts over the past few decades to make HTML dynamic by embedding PHP for the server to replace, JavaScript for the browser to replace, and subsequent cacophony of frameworks and their templating systems has taken all the joy Knuth had in computer programing away from most contemporary developers.

But for all HTML’s faults, it’s a huge improvement on PDF. Many financial institutions still love PDF files, emailing them to get filled in. Though my browser lets me view PDF files, it doesn’t support editing them, so I have to print out the form, fill it out by hand, scan these pages to email back to the financial institution, where a data input clerk invariably makes typos which could have been avoided by letting me type in my own name and address, easily done with an HTML web page. Corporate love of PDF files keeps overheads high because since they are often hard to read on a computer screen, every document gets printed, ramping up paper and toner costs.

Though LyX does let me output documents as HTML instead of PDF, the resulting web pages are not very pretty or easy to navigate. Generally, the technology Knuth developed was excellent for books — especially those with mathematical equations. How to improve on traditional books with the technology available to us is a big problem of our age.

Untangling the Web

To use TeX for documenting software, Knuth developed a package called Web (which predates the World Wide Web) consisting of two parts he named Tangle and Weave. Knuth’s Web was an automatic documentation system for Pascal programs, and is the originator of the “structured comments in code to generate reference material” found in nearly all programing languages today — JavaScript’s JSDoc, SWI Prolog’s PLDoc, Erlang’s EDoc, and Go’s godoc.

Note that while I’m using a document generation system written in Go called Hugo for this site, it serves a different purpose to godoc. Hugo uses a templating language to convert Markdown to HTML, whereas godoc creates reference material for go packages if their comments are written correctly. A pet peeve of mine is that the “howto use the automated documentation system” of every programing language I’ve encountered is badly documented. (I just started teaching myself Go, and found it annoying godoc doesn’t come with the base package).

How to Design Programs

The textbook on software development I wish I’d started with is How to Design Programs, and the first online course I wish I’d taken is one given by Gregor Kiczales based on that book.

Benefiting from the obvious advantages of well defined specifications, test-driven development, and clear documentation with examples, means weaning oneself off the bad habit of coding first, thinking second, which is difficult for those of us not educated on how to do things properly from day one, which is what How to Design Programs strives to do.

Its six step design recipe shows that documentation, specifications or interfaces, and tests are all intertwined and need to be done hand-in-hand with coding.

The authors of How to Design Programs wrote The Racket Manifesto to explain their motivation for using their own Lisp-dialect bundled with an editor and other tools, Dr Racket. One of the advantages of confining novices to Dr Racket is anyone trying to pick a text editor, test system, and document generator for, say, JavaScript, faces bewildering choices.

As someone who dabbles with lots of different programing languages, I prefer general tools. For instance, I prefer simple text editors which handle syntax highlighting for just about anything to integrated development environments. A reason I switched from Doxygen is it didn’t support syntax highlighting for code of various programming languages I used. Hugo’s list of supported code formats, on the other hand, shows what an incomprehensibly large world of programing languags and data formats are out there.

Dr Racket doesn’t come with any fancy tools to generate online documentation, but mapping its six part recipe to the way the various *Doc packages mentioned above generate HTML pages I find a powerful way to build software in a disciplined way.

I’ve tried to tie the following six sections to each step of the How to Design Programs recipe, with examples from programming languages I think have implemented good tools to do it with.

Last updated on 1 Jan 2021
Published on 1 Jan 2021

Content Footer