Book Review: *Making APL Readable*

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 38

This book proposes the adaptation of an idea of Knuth to APL2.

The purpose is to produce a method for writing APL2 which will ensure it will be readable.

The suggestion is that the programmer writes a file which is combined documentation and specification which can be processed to produce prettily printed program documentation and/or processed to extract just the code and produce a workspace.

Since processing has to be done before the code can be executed this loses the interactive nature of APL2: it introduces a step as obstructive as compilation.

Are the results worth it? One cannot tell from the book because the only fully worked example is of the function DISPLAY — the utility included with APL2 which he criticises (quite unreasonably in my opinion) for being hard to follow. The criteria for judging a utility which needs to be fast, self-contained, compact and, once issued, never to be changed or maintained are not the same as the criteria for application code which probably will have to be maintained by programmers who didn’t write it. The book is really aimed at writers of application code.

His example of documentation — DISPLAY stretched to many pages — did not strike me as the perfect way to do it although, at the end, even an expert would probably understand it better. No alternative way was offered: the obvious suggestion that clear comments could be added was not made or considered or rejected. Maybe he did not know that writers of APL2 utilities commonly remove comments when the code is fully tested so that what is issued is as compact as possible.

The author actually wants to do more than allow programmers to write readable APL2. I think there are several of these things.

He wants people to read APL2 programs with ease and he wants to force APL2 programmers to write in a way that makes this feasible. But of course there is a snag which he shows he is well aware of: the level of documentation required depends on the skill of the reader. Some people can read quite complex APL2 expressions without explanatory comment. So his standard is pitched at his own level of understanding yet this is not explicitly recognised. Implicitly it is because he suggests that S←+/X ⍝ Sum the elements of X isn’t helpful.

He wants to force programmers to write clear English and to force them to write good code divided into well-structured modules. To this end he has, in section 7.3, assembled a series of injunctions "Know the audience", "Get the reader involved", "Revise and rewrite", "Do not overwrite" and "Do not overstate" each of which is supported by a paragraph of explanation.

We wonder how many of these were used on him by his supervisor. There are whole shelves of books on how to write good clear English; maybe he had to include something about it; maybe readers will agree with his choice, maybe not.

And to follow his advice one needs to learn TEX as well as a whole lot of arbitrary rules for his APL2web product before one could start to write APL2 as he wants us to.

What he wants us to write is a mixture of text, the TEX commands to format it, the APL2 code and the specialised syntax of the APL2web system. As he admits this stuff is hard to read. Only after processing it does one get to see or print ‘Prettyprinted’ documentation. This mixture is hard to write:

Any APL2 programmer who wants to document his or her programs in the literate style must not [only] learn the APL2web syntax but must know TEX. And TEX offers quite a few pitfalls of its own. It was initially "intended for the creation of beautiful books — and especially for books that contain a lot of mathematics".

What a lot one would have to learn before writing a line of code! Could anyone who had not devised the system do it? In a PhD thesis it is understandable that the decisive test — getting someone to learn and use the system from scratch was not tried. I am not convinced and will stick to documenting code with comments and writing the manual in WinWord, importing code from tested workspaces and using Adrian Smith’s Vector APL Typewriter for the odd APL characters in a text paragraph. My prejudice is for a method he considers on page 206:

"It might be worth considering to develop a user handbook before even the first line of code has been written. A rough sketch of the handbook may be the introduction of the program documentation. Every programmer knows what the final program is to look like. The handbook does not describe the final product, but serves as an obligation to every programmer to meet the goal. A handbook is written in a different style since it communicates primarily with the newcomer. (It must permit the expert user quick access to a wanted topic!) Besides the program itself, the handbook must transmit the commitment created by the new software package to the user. If the handbook is written in advance, every programmer must feel compelled to meet the requirements of the commitment created therein and to develop an excellent product."

My method is to write the user manual first. This ensures I can state the user’s purposes in language the user can understand and asks him to agree the specification before any work is done. Once this is agreed it is usually possible to agree a good data structure. Then, if there are many staff involved, the manual can be presented to them to see if they are happy with the control mechanisms they are to operate. Changes are made to accommodate their criticism. Then the function headers and the top level comments in each function are written before entering a line of code. Glenford J. Myers’ book Reliable Software through Composite Design is a good guide to refining the design to get the best structure. Restructuring at this stage if it seems desirable wastes little work. After this the coding and testing are easy.

Christoph von Basum’s own task was even harder than the one he set his programmers: he had to explain and justify all his procedures in English, which to him is a foreign language. He should have asked a native English speaker to correct the text for him as there are many non-idiomatic phrases and even once or twice sentences where it is not clear what he intended to say. He has cords in his thesis where English arguments have threads; he has a complex software where English would insert piece of and many others. Lastly there is no index.

Book Announcement. We have just received a first announcement of "APL2 in Depth" by Norman Thomson and Ray Polivka. The publisher is Springer-Verlag, and the US price is $39.95. "Emphasis is placed on covering those APL2 language features which extend user versatility in describing data structures and communicating algorithms in ways which mirror current array-oriented thinking in computer science and software engineering". We hope to have a copy in time to review it in the October Vector.