22 Mar
2018
22 Mar
'18
3:29 p.m.
On 22/03/2018, Doug McIlroy <doug(a)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