Path: csiph.com!usenet.pasdenom.info!gegeweb.org!de-l.enfer-du-nord.net!feeder2.enfer-du-nord.net!feeds.phibee-telecom.net!newsfeed.xs4all.nl!newsfeed5.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
MIME-Version: 1.0
In-Reply-To: <jkanmg$mp9$1@dough.gmane.org>
References: <4f612b19$0$1379$4fafbaef@reader2.news.tin.it> <CAJ6cK1ZsP0bBDjSGygqt=QWpj=Pk7Z4KeDWuM-3qFTvcez6-Gg@mail.gmail.com> <mailman.660.1331771276.3037.python-list@python.org> <8e72d74f-c844-4de3-8a37-f6b1fdc2291f@y27g2000yqy.googlegroups.com> <50e9ceec-40f1-4ead-b2b6-87328b30d084@ow8g2000pbc.googlegroups.com> <cafdcc3e-96e4-4fb5-8885-a3f8115bc903@x10g2000pbi.googlegroups.com> <CAPTjJmrEovHCk_pu9fRY51uO2+QD3OaGmQnBSLe1y_HpNQ_ZQg@mail.gmail.com> <CAOFbRmKQGcK4=1nsRzZfikGTX2wPD-NAs2HmRyHsH7dd0RgHyg@mail.gmail.com> <jkah4j$rrv$1@dough.gmane.org> <CAOFbRmKsvd3asZtAtm4Lb5M_cNxAG6CjkgZA0NSV2=Kzzw=NwQ@mail.gmail.com> <jkanmg$mp9$1@dough.gmane.org>
Date: Tue, 20 Mar 2012 16:34:21 -0400
Subject: Re: Python is readable
From: Nathan Rice <nathan.alexander.rice@gmail.com>
To: python-list@python.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.842.1332275665.3037.python-list@python.org>
Lines: 37
NNTP-Posting-Host: 2001:888:2000:d::a6
Xref: csiph.com comp.lang.python:21949

>>> 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. =A0I would
>> compare the abstract of a scientific paper to the overview section of
>> a program's documentation. =A0The 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. =A0If the
>> code were sufficiently intuitive and expressive, that would be
>> redundant. =A0Of 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 independen=
tly
> 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.