I'd like to hear good arguments for not having docstrings. CatDancer has one instance above, but that particular case could be solved by instructing the editor to hide them until we want them. Source-level documentation solves so many other problems.

Documentation is essential if multiple programmers are going to touch something, which will be the case in the vast majority of projects. "The vast majority" likely even includes most peripheral work on the language itself, such as writing libraries. Keeping the documentation right next to the function/macro definition makes it that much easier to check the documentation and a lot easier to write the documentation in the first place. Even looking up automatically generated documentation on a web site is too much hassle when it could be checked interactively from your terminal.

One of the primary reasons is that we have developers in multiple countries with different primary languges; forcing everyone to write English docs would actually discourages some from writing docs. And mixing multiple languages in the source was a source of troubles (although it's getting better now for most tools and editors can cope with utf-8.)

"I love contrarian views. I disagree with this one, though."

http://akkartik.name/codelog.html

This is how it should always be done. Encoding your ideas in any programming language is a lossy operation: it's difficult or impossible to determine from an arbitrary piece of source code what the intent and purpose of the programmer originally was. Good documentation gives the missing pieces.

I've found it incredibly helpful to write the documentation of functions before the function itself. Like you, I have a small head, and unless I know exactly what I should program beforehand, it's going to be difficult and messy to keep all details in mind. Describe the intent and purpose, give a canonical example of use (single line, or a couple of more if the function is variadic), rule out illegal input, and you're set.

Note that I'm not advocating long pieces of documentation. If you cannot describe a function well in a few lines, it's too big, and it's definitely not clear to you what it should be. If the documentation is in the same place as the source code, it is worlds easier to write the documentation, write the source code, then bounce between them while developing (since both usually require iteration).

Not at all! It's been a mind-blowing experience to me to see documentation pop up in all of the arc codebase just because we had a wikipedia-like workflow.

But in my experience on large projects that kind of documentation becomes:

   # do_my_foo() is a function accepts a float and
   # returns a float, performing necessary calculations.
   double do_my_foo(double inarg) {
   .
   .
   .

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.

  (def qne (obj q)
    (atomic
      (++ (q 2))
      (if (no (car q))
          (= (cadr q) (= (car q) (list obj)))
          (= (cdr (cadr q)) (list obj)
             (cadr q)       (cdr (cadr q))))
      (car q)))

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

  (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]] 

Now, you could say that we should have a default docfile and move the inline docstrings to that, but I think that in general when you are writing and maintaining documentation, it's much easier to have it right there.