I love contrarian views. I disagree with this one, though.
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.
I think the principal argument for docstrings is that they actually make most programmers document their code, as long as the framework (help-query systems, automatic HTML generation etc.) is in place. And this in turn makes libraries that much more valuable, because it won't any longer take two hours to understand a simple, peripheral but necessary support system.
* Documentation is essential if multiple programmers are going to touch something, which will be the case in the vast majority of projects.*
I don't know. (a) This is Lisp, we need one tenth the programmers of other languages meaning it is one tenth likely anyone will ever look at my code. (b) Even in tall buildings on projects with twenty people when I was on a trekking vacation in the Andes and my program broke, guess whose yak-phone rang?
Although this is not a very general example, I tend to oppose in-code docstrings for a couple of reasons.
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.)
Another is that I see sometimes documentation and code need different structures; tying one doc for each global entry skews documents away from the better structure. (This doesn't exclude having a small 'remainder' entry per each code, which is useful as you said that you can check in the editor. )
And don't forget good documentation, preferably built-in. Whenever I am exploring something I haven't done before, it's a great boon not having to read the sources, or even look it up on the web. Python's help() is wonderful.
