Re: [Axiom-developer] Literate programming

[Tassilo Horn]

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?

Bye,
Tassilo