[FRIAM] coding versus music

[Russell Standish]

On Wed, Jan 27, 2021 at 11:45:46AM -0700, Prof David West wrote:
> 
> But — a program has two audiences: the machine (no communication here) and
> other programmers (tons of miscommunication here). This is what the reference
> from Eric Smith talks about. There is an entire, usually ignored, paradigm in
> computer science called "literate programming"  — the most prominent advocate,
> Donald Knuth.
> 
> If one were skilled at literate programming, one would be communicating to
> another programmer (or herself at a later point in time) all the knowledge and
> meaning necessary for the latter to understand, modify, enhance, or correct the
> program as needs be. If possible this would be a communication skill worth
> developing — might lead to more precise and accurate communication outside the
> world of the computer.

Literate programming is alive and well in modern software engineering
- it just isn't called that. Knuth's tools which involved a special
input language, a tool for converting that to compileable Pascal and
Latex for producing humane readable printouts of the code were
fantastic for the 1980s, but are rather dated for current software
development requirements.

In C++, one uses a tool called Doxygen, which parses standard C++
code, and produces HTML, Latex and other possibilities. The "dot"
network graphics tool is used to produce interactive UML diagrams of
the class structures, and source code is annotate with hyperlinks
allowing you to click on (say) a variable name, to find out what type
it is, where it is defined and so on. Plus, there is a huge amount of
doxygen markup features available, allowing things like embedded LaTeX
equations, or adding in crafted HTML links and so on. In short it does
everything Knuth's web tool did, and more, without the need to write
in an idiosyncratic source language.

When I come across a piece of unfamiliar code, the _first_ thing I do
is run doxygen on it, and then start reading the code using a web
browser. People are sometimes amazed at how quickly I find my way
around a new code base - when that happens, I let them in on my
superpower, ie doxygen.

Doxygen handles a number of programming environments, Java, C#,
Fortran even, though not Python nor Javascript alas. Other
environments have similar tools, of greater or lesser power: eg Java
has Javadoc (which is broadly compatible with Doxygen, in fact).

Knuth should be commended for being 30 years ahead of his time with
literate programming, and should be glad the industry does finally
"get it", even if his contribution is largely forgotten, and not
acknowledged by the hordes of software engineers currently practising.


-- 

----------------------------------------------------------------------------
Dr Russell Standish                    Phone 0425 253119 (mobile)
Principal, High Performance Coders     hpcoder at hpcoders.com.au
                      http://www.hpcoders.com.au
----------------------------------------------------------------------------