Cross posted from my blog: Analyze the Data not the Drivel
When faced with unfamiliar program code Roger Hui, the cocreator of the J Programming Language would sometimes wipe out all the code comments. He told me this forced him to concentrate on the actual code and not the opinions of previous developers. Roger was an exceptional programmer; he knew that program comments are often dated, misleading and wrong. And, the only way to "correct the comments" is to read the code; so why not just read the code and skip the philosophy? Roger's comment purges underscore an important point. However you document your code, it must be better than the null or empty document.
With this in mind, I wrote a few versions of this post, but I hated them all. Then I realized that jodliterate PDF documents mostly do what I want. So, instead of rewriting MirrorXref.pdf, I will make a few comments about jodliterate group documents in general. If you're interested in using SQLite with J, download the self-contained GitHub files MirrorXref.ijs and MirrorXref.pdf and have a look.
jodliterate Group Documents
jodliterate group documents are directly generated from JOD
dictionaries using J, pandoc, and LaTeX. Group documents have three major parts.
An overview.
Complete typeset source code.
A global word index.
The source code and index sections are self-explanatory, but a few
remarks about overviews are warranted.
The overview might have several subsections. There's usually a
hyperlinked Interface subsection. J doesn't have formal interfaces like many programming languages. The words listed in the Interface section are words you will use when running the script. The Interface section highlights where to get started.
For complex scripts, there is usually a Using subsection MirrorXref.pdf's Using subsection is typical.
Finally, there might be a Code Hints subsection. Code Hints are lists of hyperlinked words that you should heed.
For more, take Roger's advice and read the code.
Top comments (0)