From mboxrd@z Thu Jan 1 00:00:00 1970 From: cym224@gmail.com (Nemo) Date: Thu, 22 Mar 2018 10:29:17 -0400 Subject: [TUHS] Comments in early Unix systems In-Reply-To: <201803221349.w2MDn23w100793@tahoe.cs.Dartmouth.EDU> References: <201803221349.w2MDn23w100793@tahoe.cs.Dartmouth.EDU> Message-ID: On 22/03/2018, Doug McIlroy 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 >