> 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
