Path: csiph.com!usenet.pasdenom.info!gegeweb.org!de-l.enfer-du-nord.net!feeder1.enfer-du-nord.net!tudelft.nl!txtfeed1.tudelft.nl!multikabel.net!newsfeed20.multikabel.net!news2.euro.net!newsfeed.xs4all.nl!newsfeed5.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
Return-Path: <python-python-list@m.gmane.org>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.003
X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'subject:Python': 0.05; 'agree,': 0.07; 'received:verizon.net': 0.07; 'terry': 0.07; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'displayed': 0.10; 'docstrings': 0.16; 'reedy': 0.16; 'wrote:': 0.18; 'exists': 0.18; 'jan': 0.19; 'header:In-Reply-To:1': 0.22; 'string': 0.24; 'code.': 0.26; 'code': 0.26; 'function': 0.27; 'fact': 0.27; 'pm,': 0.29; '(as': 0.31; 'pretty': 0.31; 'does': 0.32; 'scientific': 0.32; 'header:User-Agent:1': 0.33; 'header:X -Complaints-To:1': 0.34; 'to:addr:python-list': 0.35; 'received:org': 0.36; 'called': 0.40; 'to:addr:python.org': 0.40; 'human': 0.62; 'journal': 0.67; 'nathan': 0.84; 'abstracts': 0.91; 'medium.': 0.91
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Terry Reedy <tjreedy@udel.edu>
Subject: Re: Python is readable
Date: Tue, 20 Mar 2012 14:09:11 -0400
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>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
X-Gmane-NNTP-Posting-Host: pool-74-109-121-73.phlapa.fios.verizon.net
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:8.0) Gecko/20111105 Thunderbird/8.0
In-Reply-To: <CAOFbRmKQGcK4=1nsRzZfikGTX2wPD-NAs2HmRyHsH7dd0RgHyg@mail.gmail.com>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.837.1332266975.3037.python-list@python.org>
Lines: 15
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1332266975 news.xs4all.nl 6938 [2001:888:2000:d::a6]:43613
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:21940

On 3/20/2012 12:55 PM, Nathan Rice wrote:

> I agree, docstrings/code comments are a pretty obvious indication that
> code (as it exists currently) fails as a human communication medium.

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.

-- 
Terry Jan Reedy