> > 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 _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
