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 -- 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
