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 -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
