From mboxrd@z Thu Jan  1 00:00:00 1970
Message-ID: <d7035eea052c8ed28dd9e4c0b0f1930f@bellsouth.net>
To: 9fans@9fans.net
Date: Fri, 26 Dec 2008 11:25:33 -0600
From: blstuart@bellsouth.net
In-Reply-To: <20081226142756.GA609@polynum.com>
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit
Subject: Re: [9fans] Changelogs & Patches?
Topicbox-Message-UUID: 7114ab1a-ead4-11e9-9d60-3106f5b1d025

> I use CWEB (D. Knuth and Levy's) intensively and it is indeed
> invaluable.
> It doesn't magically improve code (my first attempts have just shown
> how poor my programming was: it's a magnifying glass, and one just saw
> with it bug's blinking eyes with bright smiles).

Back when I used CWEB on a regular basis (I don't find myself
writing as much substantive code from scratch of late), I
experienced an interesting phenomenon.  I could write
pretty good code, almost as a stream of consciousness.
The tool made it natural to present the code in the order
in which I could understand it, rather than the order the
compiler wanted it.  But it was the effect of this that was
really interesting.  I found that as I wrote I'd think in terms
of several things I needed to do and I'd put placeholders in
(chunk names) for all but the one I was writing just then.
As I'd finish a chunk, I'd go back an find another one
that I hadn't written yet, and I could easily pick them in
the order I figured out the way I wanted to handle it.
At some point, I just ran out of chunks that needed to
be written, and the code would be done.  It was almost
as if the completion of the code snuck up on me.  At
first, it was sort of a "maybe Knuth's on to something
here" but it happened often enough that I now consider
it a basic feature of the style.

Back to the topic in question though, I did find that
writing and maintaining good descriptions tool almost
as much discipline as any other code documentation.
I did have to resist the urge to leave the textual part
of a chunk blank and just write the code.  I also had
to be diligent about updating the descriptions when
the code changed.  But for whatever reason (asthetics,
tool, living up to Knuth's example...) it did seem a
little easier in that context.

However, in terms of changelogs and such, I'd say
that's still an open question.  It would seem that there
should be some way to automate the creation of a
changelog (at least in the form of a list of pointers)
from the literate source.  But the literate style itself
doesn't really seem to create anything new in terms
of the high level overview that you'd see in release
notes or changelogs.

BLS