Re: [Axiom-developer] Literate programming

[daly]

On Fri, 2011-10-28 at 11:59 +0200, Tassilo Horn wrote:
> Hi Tim,
> 
> while I agree that good documentation is important for maintaining and
> developing further a given code base, I always wonder how literate
> programming deals with refactoring and larger restructuring.  I mean, in
> basically all software projects I'm involved in, developers have a hard
> time in keeping at least the most integral documentation up-to-date,
> e.g., docstrings, JavaDocs, etc.
> 
> Now I consider a some literate code base, i.e., a book that describes
> the complete system in a very detailed manner including the reasons to
> design it that way.  That's awesome for developers joining the project,
> but doesn't it hinder any further development?
> 
> For example, I'm currently reworking some paper that includes code for
> some model transformation.  If I had the right tools, I could extract
> the source code from the latex files and have a running transformation.
> But now, I had to do some minor modifications to the code which took me
> about 5 minutes, but adapting the surrounding text takes me hours over
> hours.  I think, that's an experience many people have made: changing
> source code of a system that is well-designed and understood by the
> developer is much easier to do than changing a cohesive text in natural
> language.  In code, I have an automated, picky lector that always reads
> the complete "book" after each change I make (also known as compiler).
> In plain text, only a human can verify consistency and only in very
> narrow borders.
> 
> Well, that's more text than I intended to write. ;-) So short story
> long: how do you manage conistency of docs and code in literate code
> bases?

Hard work? Book authors face the same problem. Every new change to
Clojure makes more work for the authors.

One side-effect of Literate Programming is that you re-arrange your
code to fit the presentation. As a result you bring together chunks
that are all related (e.g. the code to support Red-Black tries).

I would claim that refactoring "in the large" is unlikely in a
literate program because you have to think through the code in order
to explain it clearly. But if you do a large refactor then it is 
just hard work. For small refactorings you might not have to change
the explanation at all.

Clojure is pretty well "firmed up" at this point. I don't know if
there is going to be a large rewrite of the fundamentals.

Tim Daly