Re: [Axiom-developer] database fixes

[Gabriel Dos Reis]

root <address@hidden> writes:

| > > 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.

What the documentation perspective, it is far more important to
explain the goal, what the file is trying to do and whay it is doing
it.  

Comment saying "I'm assigng the value of y in the location x" in front of

   x := y

is contentless and irritating.

| 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.


yes, *why* is the main important thing.

-- Gaby

[...]

| 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)

As I'm sure you know; the issue there is really different, and should
not be conflated with this one.

-- Gaby