[Axiom-developer] Re: do clojure and la(tex) have something in common ?

[Raymond Rogers]

    This sounds very similar to the items mentioned in: FIPS PUB 105
www.itl.nist.gov/fipspubs/fips105.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
address@hidden
http://lists.nongnu.org/mailman/listinfo/axiom-developer