Re: [Axiom-developer] Heidegger, literate programming, and communication

[Mars0i]

Tim,

Your project of LP'ing the Clojure internals is not at all  inconsistent with my view.  That is code that would benefit from being widely understood, even by people who won't maintain it.  I learned a lot from reading the "Lions" book on an early version of Unix, even though I probably never even used hardware old enough to run it.  (On the other hand, I'm not sure that there should be documentation that explains the complexities of the chunking mechanism both at the definitions of `map` and `doseq`, for example.  That seems redundant.  Maybe LP software has convenient ways of dealing with that sort of issue, though.)

And I agree that won't can't know what code will live for 25 years, and what won't, and how many people will have to maintain the code.  So one approach is simply to assume that all code will live a long time and be maintained by many people, many of whom will be unfamiliar with the code.  But that means that you waste a lot of time on code that gets put aside (for reasons other than lack of documentation). 

Yeah, there are tradeoffs.  We have to make our best judgments.

One option: Write with whatever documentation you think will help the code's forseen uses.  Then, if you discover later, that it needs better documentation, write it then.  That won't be as easy as writing it in the first place: In hindsight, it's less efficient, but it may be more efficient overall across all projects.  (i.e. one "faults in" the documentation: It's sometimes most efficient to allocate all of an executable's image and heap as soon it runs, but modern OSes instead often allocate memory only as needed, which, in hindsight, is less efficient, but overall, makes for a more efficient system.)

(I think I am the "Gary" mentioned above, although that isn't my name.  But I'm happy to take on that name in this discussion.)

-Gary