[TUHS] Comments in early Unix systems

[Nemo]

On 22/03/2018, Doug McIlroy <doug at cs.dartmouth.edu> wrote:
[...]
> For imoortant code, custom is to describe it in a separate
> paper, which is of course not maintained in parallel with
> the code. In fact, comments are often out of date, too.
> Knuth offered the remedy of "literate programming", which
> might help in academic circles. In business, probably not.
> Yet think of the possibility of a "literate spec", where
> the code grows organically with the understanding of what
> has to be done.

At a previous company, we used Ramsey's noweb with good results.  The
code was very heavy in math;  being able to read the typeset
explanation alongside the code was very helpful, especially for
understanding the optimization transformations.  (We also began to
include Xfig diagrams to document data flow and so on.) The next
manager decided to describe the code in separate documents, with mixed
results.  In hindsight, I probably would not have used noweb on the
typical stuff but I would definitely use noweb again to document the
math-intensive stuff.

N.

>
> Doug
>