Re: [Axiom-developer] Re: A modest proposal

[C Y]

--- Stephen Wilson <address@hidden> wrote:

> The build environment is not an issue for me at all.  If there is
> complication, it is due to the fact that there is no clean
> integration between the tools required to both build the system and
> extract the code/document bits.  This is one reason why I am excited
> about asdf-literate, as it should significantly simplify the build
> as it understands the model.  We need the proper tools for the job,
> and if they do not yet exist, we can create them.

Bingo.  None of what we're doing with pamphlets or compiling the system
is fundamentally hard (except maybe the def* parsing, but that can come
later) and it's just a question of teaching the tools to deal with it
correctly.

> I dont do that myself.  I write my code as most other programmers do.
> I write it and use traditional comments as a form of documentation. 
> I do most of my coding in Lisp, which for the most part does not care
> about things like the order of definitions.  So I can code and
> document and build towards  a literate document.  Its not yet a
> pamphlet, and the comments lack LaTeX markup,  but its a form of a
> literate document.  It is no different than any other pice of code
> written by any other programmer, except that the comments might seem
> a tad verbose.

I think CFFI's comments are like that, come to think of it...

> Once I have polished a file, once it is looking good and stable and
> Im relatively sure it is up to snuff, It is pretty straight forward 
> to convert to a pamphlet.  I dont resent the need to convert the
> code.  I view it as an opportunity to audit and re-check.  Something
> you can never do enough of.

Amen.

> So the rpocess of writing a pamphlet file is something of a support
> structure for writing nice code -- something you want anyways before
> you even think about pushing a change out to the mainstream.
> 
> Of course, others might write literately from the beginning, but
> thats not how I do it.  I would find that approach to be restrictive
> and unproductive.  But thats just me.  Fortunately, nobody is
> telling me how I should go about it.

Right.  The way I do it is close to that, but because I usually lack
the domain knowledge to just start writing code I will begin writing
the background parts of the paper as a way to educate myself.  (The
Units and Dimensions draft is an example, not yet finished).  Once I
understand it well enough to have an idea of what should be done, I
will fire up sbcl and start poking around trying things and figuring
out how pieces I am going to need should be done.  From there, its
usually an iterative process of adding working pieces to the pamphlet
and documenting them, and then figuring out the next piece.  Then a
cycle or two of figuring out if I did it the right way, and if not
re-doing whatever.  Once the program begins to reach a working stage, I
usually convert over to editing just in the pamphlet - by that point
there is enough functionality in the pamphlet that I load that when I
figure out the next piece.

There is a helpful quality about being forced to write out ideas - it's
a variation on the "to teach someone you must truly understand the
material" idea.  For already skilled developers it probably feels more
like a waste of time, but for me it really helps.

> Moreover, very few files in axiom are truely literate.  They are just
> shells, just raw code waiting to be improved.

Yep.

> > And at the same time the raw pamphlet format source code is even
> > more awkward and obscure than the original "illiterate" source code
> > by the interposed presence of coding and documentation which is
> > normally otherwise "out of the way".
> 
> This is one point to which I partially agree with.  The format is
> somehow `odd' -- it is not native to the programming language in
> which your writing.  However, it is fairly native to the task of 
> writing a document, but that is what your doing.  

We need better editor support to make that part seemless.  I have a few
ideas about that but it's down the road.

> This is the main point of my post.  If you agree in principle with
> the goals of the Axiom project then there is no real hill.  You can
> get to the top either by doing somersaults of by taking the
> elevator.  The challenge is discovering for yourself what the path
> of least resistance is, what works for you.

Right.  There is no getting around the fact that a literate
implementation of something is a lot of work, but the idea of that work
is to make something that is "finished" - it won't have to be rewritten
in 30 years because someone can't understand what it is doing.  (If
there's a better algorithm out there then of course that's different,
but the rewrite would have been needed in that case regardless.)

Cheers,
CY



       
____________________________________________________________________________________
Moody friends. Drama queens. Your life? Nope! - their life, your story. Play 
Sims Stories at Yahoo! Games.
http://sims.yahoo.com/