Literate Programming and Leo

jko9 writes "First proposed almost 20 years ago by Donald Knuth, the idea of Literate Programming is basically that of making program documentation primary, and embedding code in the documentation, rather than vice versa. Despite some obvious advantages apparent to anyone who has struggled to understand a poorly documented program, literate programming never really caught on. That all could change, however, with the release of a new program called Leo, written by Edward K. Ream. Leo supports standard literate programming languages like noweb and CWEB, but with a crucial difference - Leo adds outlines. The effect is striking: overall organization of a program is always visible and explicit. Much of the narrative of the documentation gets placed in the outline, making documentation simpler, and allowing viewers to approach the code at various levels of detail. Screenshots and tutorials for Leo are here - if that site gets slashdotted, you can download the visual tutorials in .chm form or html form from Leo's Sourceforge site. Leo is an open source program written in Python. Any current practioners of Literate Programming techniques out there? People who have tried it and given it up? Can the addition of outlines to Literate Programming make it more powerful / popular?"

Comments

Re:Literate programming versus continuing developm

[Pseudonym]

Whether there is a performance penalty to such wrapping is hard to say. Generally, there will be some performance penalty for the "indirection" needed for hiding implementation. [...] Some programmers get obsessive over speed for no good reason, and make stupid (change-unfriendly) code as a result.

Repeat until enlightened: Unless you have an unlimited amount of programmer time to expend, long-term performance is a consequence of maintainability.

The "big" performance improvements are generally algorithmic in nature. They're what you get when you replace an O(N^2) algorithm with an O(N log N) algorithm, or when you replace an O(N log N) algorithm with an O(N log N log log N) algorithm which exploits cache coherency much better.

When you find that you need to change one algorithm or data structure with another (and you will), you might think twice before doing that to an unencapsulated implementation, whereas doing it to an encapsulated implementation will be much cheaper. Moreover, with an encapsulated implementation, you can play with several different implementations until you find the best one for the situation at hand.

Yes, your code may have perform better had you written an unencapsulated version of the most appropriate algorithm/data structure to begin with. What a wonderful world it would be if software engineers were also clairvoyants. :-)

(BTW, you don't need OOP to wrap collection handlers.)

No, you don't. You at least need abstraction and at most you need encapsulation. These are a subset of the problems that OOP solves, but OOP is not the only solution to those problems.

So while you don't need OOP, if you're working with a system which already has it, you might as well use it unless there's a good reason not to.