Python is readable

[Nathan Rice]

>>> The fact that scientific journal articles start with a documentation
>>> string
>>> called an abstract does not indicate that scientific English fails as a
>>> human communication medium. Function docstrings say what the function
>>> does
>>> and how to use it without reading the code. They can be pulled out and
>>> displayed elsewhere. They also guide the reading of the code. Abstracts
>>> serve the same functions.
>>
>>
>> A paper, with topic introduction, methods exposition, data/results
>> description and discussion is a poor analog to a function.  I would
>> compare the abstract of a scientific paper to the overview section of
>> a program's documentation.  The great majority of the docstrings I see
>> are basically signature rehashes with added type information and
>> assertions, followed by a single sentence English gloss-over.  If the
>> code were sufficiently intuitive and expressive, that would be
>> redundant.  Of course, there will always be morbidly obese functions
>> and coders that like to wax philosophical or give history lessons in
>> comments.
>
>
> Both abstracts and doc strings are designed to be and are read independently
> of the stuff they summarize. Perhaps you do not use help(obj) as often as
> some other people do.

I find help() to be mostly useless because of the clutter induced by
double under methods.  I use IPython, and I typically will either use
tab name completion with the "?" feature or %edit <obj> if I really
need to dig around.  I teach Python to groups from time to time as
part of my job, and I usually only mention help() as something of an
afterthought, since typically people react to the output like a deer
in headlights.  Some sort of semantic function and class search from
the interpreter would probably win a lot of fans, but I don't know
that it is possible without a standard annotation format and the
addition of a namespace cache to pyc files.