Re: [Axiom-developer] database fixes

[root]

> > On Monday, October 16, 2006 8:47 PM Waldek Hebisch wrote:
> > > ...
> > > 1) ATM I can not add much value to what is already there --
> > >    I can read the code but the classic rule of documentation is
> > >    "documentation should not repeat the code"...
> > 
> > Actually this classic rule of documentation is *not* appropriate
> > to literate programming. In a literate program the document contains
> > the code so it certainly "repeats the code" in that sense. The code
> > illustrates and implements the ideas described in the document. Code
> > and documentation are not two separate things.
> >
> 
> .....[snip].....
> 
> is better (I admit that as a reader I find the first version much
> better).

i think that we need actual sentences to describe what the code does.
we also need paragraphs that explain the big picture of what the file
is trying to do.

axiom has tons of "dirt simple, obvious code". i know because i always
try to write the easiest, most straightforward code i can. now, 15 years
later, i cannot remember WHY i wrote the code. i can tell you that it
manipulates a data structure and how it manipulates it. i can't tell you:

  why the data structure exists
  what the fields mean
  why that structure was chosen
  why the code manipulates the data (fetch, store, modify) 
  what design choices were rejected and why
  why this file exists and what problem is it solving

i agree that documentation like:

  (setq x 3) ; set x to 3

is useless. but if it said

  (setq x 3) ; this maximizes the optimization level for space

then it would be useful. the issue isn't "line-for-line".
the issue is writing for people, not the machine.






 
> > > 2) AFAIK Tim is working on the same file and scattered changes
> > >   (or some re-organization) is likely to create conflict with his
> > >   changes.
> > 
> > No problem. That is why we use version control systems. You both
> > can make changes and conflicts can be easily resolved.
> > 
> 
> version control detects conflicts. One has still manually resolve them.
> If Tim permute hunks in one way and I in another way then resoving
> conflits will require some work.
> 

don't let this stop you. i ALWAYS hand merge EVERY change to the system
so i have a way of resolving every conflict. i do this because axiom is
not some piece of code someplace but an idea in my head. unless i put
the changes into my head the whole system will become "magic". i don't
believe in magic and i can't write correct programs if i don't understand
the programs.

so change anything you want..... but make sure you explain the how and
why of the changes. pretend you're writing the documentation for me
(because i'm going to read it that way anyway).







> > What Gaby (and Tim Daly) are saying is that when you submit patches,
> > these patches should be changes to the pamphlet files which result
> > in an easy to understand document (e.g. in dvi format) and which
> > produce your modified code when input to notangle.
> >
> 
> The patch I wrote changed the paphlet file.  I admit that I did not
> use dvi viewer to check formatting, but since the parts I changed
> follow textual format using only text terminal should be OK.  

ummm, well, the pamphlet file IS the source code.
if you changed the lisp code would you post a change without trying it?
if you changed the latex would you post a change without trying it?

it's all 'one thing', not code+documentation.
think of latex as a compiler stage.
always latex the sources, always compile and run the sources.

(gaby and bill disagree with me)

t