This sounds very similar to the items mentioned in: FIPS PUB 105 www.itl.nist.gov/*fips*pubs/*fips*105.pdf Section 2.7.1 The documentation requirements depend upon the size and type of the audience; and the expected lifetime of the software. Ray
The hope is that since Clojure is all about breaking away from the past, we would consider breaking away from the past method of program development also. Unfortunately, this requires more work from a programmer. Is it a factor of ~1.5? Who knows. I use the factor-of-3. The factor-of-3 comes from the rule of thumb which I've seen somewhere and have been extending as I learn. There is a relation between the unit of work and the task you are trying to do, based mostly on your audience. Programmers never seem to get beyond the 1-unit mindset, "write the code and they will come". Software tends to scale as a factor of 3. My current scale is: 1 unit : Something you do for yourself (e.g. 1 week coding) 3 units : package it up to give to another person (involves collecting files, copy, chat, etc) 9 units : package it up for a group (write install instructions, deal with XP/Linux/Mac, handle missing prereq software, phone/email support) 27 units : make it open source (sourceforge/mailing list/web pages/email support/ install scripts/spam/server setup/user support/ floss license debate) 81 units : make it commercial (corporate structure/CEO/lawyers/trademark/copyright/ accounting/reporting) 243 units : make it live forever (deep documentation/literate programming/ finding the right ideas/standards/courses) Clojure isn't commercial so we can skip that power-of-3. My power-of-3 estimate says that for EVERY week of work that Rich does on Clojure it will require 27 weeks of work to keep it viable as open source. It will require 81 weeks to make it live. To make it viable beyond Rich's contribution requires a whole ecosystem which includes standards/books/videos/courses, etc. Literate programming is, by my belief, the way that helps keep the software viable. It is, however, a HUGE amount of work compared with writing the code. Probably a factor of 3 :-) Unfortunately, if the ideas are not written down now then they probably never will be written down. Without a required standard of literacy, programmers will never do it. Even requiring test cases is considered a "major innovation" (e.g. TDD). Bill Hart, from the Sage project, said: "Another thing I've been enjoying lately is literate programming. Amazingly it turns out to be faster to write a literate program than an ordinary program because debugging takes almost no time." (http://axiom-developer.org/axiom-website/documentation.html) so on balance it might be ~1.5 rather than 3. Who knows? If you look at common lisp, the effort to write the code that handles, say string processing, is trivial compared with the effort to document it, make it a standard, get it through the various social aspects and committees. Clojure has a LONG way to go. There is no royal road to viable software. Tim ka wrote: > Hi Tim, > > Thanks! for such a detailed response. Really got things in > perspective for me, my thinking yet isn't of such large scale. > > So you say literate programming is for those who are writing code that > will live for decades to come and that writing literate programs takes > ~3x resources. > > Is there a stripped down version of literate programming that will > benefit the majority of programmers who are just average coders, > writing a few APIs etc. that would probably take say ~1.5x resources? > I'm just curious as the concept seems really good. I'm not sure how > many people are willing to do 3x work for writing their APIs. I > absolutely agree with your point of documenting (with the goal of > communicating to people) design decisions; and comments are not enough > for the same. > > Very recently I started to get interested in code formalism (i.e. > mathematically proving programs), although literate programming is not > geared in this direction, it might play its part. > > - Thanks > > _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer
_______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer