I used to find the notion of literate code attractive, but right now my dissertation prototype implementation is undergoing some serious redevelopment and the horribly out-of-date docs are dragging me down. Now I find myself wishing I'd kept them separate.
3 comments:
Have you looked at Zed Shaw's "Idiopidae" for keeping the two separate. His recent blog post on Vellum has a sample PDF created with it:
http://www.zedshaw.com/blog/2008-04-26.html
I had exactly the same problem with the literate implementation of InforML for my dissertation. It was great for a while to have the inference rules right next to their implementations, but I just wasn't able to keep it up to date after multiple refactorings.
Well, yeah... sorta.
I've only started dabbling in literate programming in a more serious way recently so, I might change my mind but:
Hard deadlines and goals that can conflict with creating the best possible program, as with a thesis, seem incompatible with the technique to me (unless the problem size fits very easily into the schedule, unlike most thesis projects).
It is a technique that slows you down, no doubt about it. But it's also a technique that can (but is certainly not guaranteed to) help you robustly create programs of unusually long lasting value.
When you make some mis-step in a complex program and have to unwind and re-do or re-factor a lot: that can be quite painful no matter what technique you are using. One of the luxuries of the literate approach seems to me (so far, knock on wood) that it can help minimize the number of occasions on which you have to do that. The way in which the literate technique can help there is that, if you have the liberty to go really slow and write carefully, concentrating a lot on the document, that discipline helps you think things through in advance.
I may very well completely eat my words, though, depending on the future of my current experiment with it. I take your comment at least as much as a "heads up" warning of what I might be in for as I do something to disagree with.
-t
Post a Comment