If my opinion counts for something, I totally support your view, CatDancer. The same happens to me, I always want to remove distraction. But it's a personal thing, I realize that. Everyone has deep reasons to prefer their own way, and I am no exception. I also should confess that I program mostly "alone", that's why my opinion maybe doesn't count as much as everyone else's.
In my case, I kind of think about it as "typographical" reasons. For instance, all manuals of typography tell you that it's uncomfortable to read very long lines of text if they are too close (in fact, this forum is above the limit, whereas PGs essays, if you remember, are almost perfect). The reason is that when you try to find the exact line that is the continuation of the one you are on, you have to search. Best measures for this have been tabulated by the professionals, of course. And, you know, lately I've discovered myself trying all the time to make programs not surpass the 65th column, and using the "wc -L" command all the time, so that programs occupy mostly your field of vision without moving your eyes... Stupid maybe? Perfectionism? Yes, I know. But I think this goes in the lines of your comment, since documentation breaks this 'unity' of code, I don't like it in the middle.
And the one thing that has attracted me towards Arc is, as a matter of fact, "the PG style", this minimalist, amazing (for my taste) coding style that I saw in "On Lisp" and "ANSI Common Lisp". It feels right to me, and you feel that code becomes a 'definition', so I now think I should be trained enough to read "arc.arc" _without_ documentation, as if I was reading math or something. And since Arc seemed like a language built with those principles, the addition of documentation, while certainly useful, didn't feel right to me.
In fact, I would die to know what PG thinks about this... ;)
I find it hard to believe that reading the code can be a replacement for
documentation. For example, I would find a one-line description much more
useful than trying to figure out:
In case anyone was wondering... this is Arc's enqueue operation, which atomically adds obj to the queue q. Arc's queue data structure provide constant-time enqueue, dequeue, length, and conversion to list operations. My point is that documentation is a good thing, since understanding raw code can be difficult for mere mortals such as myself.
>It feels right to me, and you feel that code becomes a 'definition', so I now think I should be trained enough to read "arc.arc" _without_ documentation, as if I was reading math or something
Sure, sure. Then you completely forget wtf 'on is supposed to do, and how it's different from 'in, and have to read it again.
Well, if you completely forget about some function, you will have to read something anyway. I guess what you say is that the documentation is obviously more readable than code, but I'm not so sure...
It probably varies. Natural language is a mess, and in the hands of geeks...ugh. So if I have an interesting function to understand I would just as soon see the code. But if I am looking at standard library stuff it will be hard to muck up the one very short sentence description. Add to that that we have a new language with a lot of shortcut syntax and that its a Lisp and a lot of non-Lispers are hopefully looking at the language, I think maybe the ball was dropped when we were told to just read the code, as much as I grok that sentiment. It is something I am much faster to say when we have people asking about application code in a language everyone asking is supposed to know.
(mac in (x . choices)
(w/uniq g
`(let ,g ,x
(or ,@(map1 (fn (c) `(is ,g ,c)) choices)))))
(mac on (var s . body)
(if (is var 'index)
(err "Can't use index as first arg to on.")
(w/uniq gs
`(let ,gs ,s
(forlen index ,gs
(let ,var (,gs index)
,@body))))))
versus:
(from "arc.arc")
[mac] (in x . choices)
Returns true if the first argument is one of the other arguments.
See also [[some]] [[mem]]
(from "arc.arc")
[mac] (on var s . body)
Loops across the sequence `s', assigning each element to `var',
and providing the current index in `index'.
See also [[each]] [[forlen]]
The main point is this: documentation says "what this code should do". Code says: "this is how we do it". In many cases, the user of a function or macro is interested in what the code is supposed to do; how it's done is less important.
Err, sorry, but that's not what I meant. Just tooting my own horn ^^. In any case, the documentation can be improved. I did most of that while I was sick, and I'm not 100% sure it's correct - there may be subtle uses that I haven't documented. Also, the docs are far from complete - there are a huge bunch of functions without decent "see also" links. And I've only completed arc.arc yet, still haven't had time to do srv.arc, html.arc, app.arc, and prompt.arc
