Path: csiph.com!aioe.org!rt.uk.eu.org!newsfeed.xs4all.nl!newsfeed4.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <rosuav@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.021
X-Spam-Evidence: '*H*': 0.96; '*S*': 0.00; 'subject:code': 0.07; 'uses.': 0.09; 'violates': 0.09; 'python': 0.11; 'broaden': 0.16; 'declaration': 0.16; 'docstring': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16; "function's": 0.16; 'sat,': 0.16; 'wrote:': 0.18; '(not': 0.18; 'slightly': 0.19; 'van': 0.27; 'header:In-Reply-To:1': 0.27; 'function': 0.29; 'generally': 0.29; 'message-id:@mail.gmail.com': 0.30; '(which': 0.31; 'code': 0.31; 'comments': 0.31; 'subject:other': 0.31; "i'd": 0.34; 'but': 0.35; 'received:google.com': 0.35; 'really': 0.36; 'possible': 0.36; 'should': 0.36; 'to:addr:python-list': 0.38; 'pm,': 0.38; 'explain': 0.39; 'to:addr:python.org': 0.39; 'consists': 0.60; 'skip:* 10': 0.61; 'jul': 0.74; 'subject:people': 0.84; 'albert': 0.91; '2013': 0.98
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=kQQ4ZZbiY4ou5XrovxsGV3XP/gCAdyV0iCi27UR/ev0=; b=v9Y8IOpF2S7VmLv1Zm8htSm3btpTuPK8qDck3/dIf2Vj8GXeA6lo7b3W2XlM6gLSCu 0VYYF6nscVQOXciUXnjKB/mDajkC95MJtmJ4Zf/Nwqo8UZ4q/jzP2VLVIOx5r8bJSCSM MKmt344an9Rvg0KhjIkXOEnGDdYoHqZQc2VNa0vqHkxJjopDAJDqEFzjb6HzzZb33ngd MnzJ/IKbewV0RVMHZu8FitcMs2kqQFdKFVzfH+HFt6nJT0rIiRjXZdtuy+FlvD2uOxMv w6ipUw4f2YIKR5htpLOdYsEIDAB/pa6P0k3nfI7FlHmEyLwKpLF4IRKTJQgQHFfpqWa6 7xAQ==
MIME-Version: 1.0
X-Received: by 10.220.169.146 with SMTP id z18mr5619849vcy.80.1374932470540; Sat, 27 Jul 2013 06:41:10 -0700 (PDT)
In-Reply-To: <51f3c764$0$26864$e4fe514c@dreader37.news.xs4all.nl>
References: <66c25416-eaa5-4ac1-a71d-2b2948dec2fb@googlegroups.com> <b023f6e6-a11d-4d05-a126-e3cc49cb367e@googlegroups.com> <51f3c764$0$26864$e4fe514c@dreader37.news.xs4all.nl>
Date: Sat, 27 Jul 2013 14:41:10 +0100
Subject: Re: Understanding other people's code
From: Chris Angelico <rosuav@gmail.com>
To: python-list@python.org
Content-Type: text/plain; charset=ISO-8859-1
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
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.5171.1374932473.3114.python-list@python.org>
Lines: 14
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1374932473 news.xs4all.nl 15998 [2001:888:2000:d::a6]:43607
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:51357

On Sat, Jul 27, 2013 at 2:13 PM, Albert van der Horst
<albert@spenarnc.xs4all.nl> wrote:
> If the code is really tidy, it is possible to understand a function
> using only the *documentation* (not the code itself) of any function
> or data it uses.

I'd broaden that slightly to the function's signature, which consists
of the declaration line and any associated comments (which in Python
should be in the docstring). The docstring kinda violates this
concept, but what I generally try to explain is that you should be
able to understand a function without reading any of the indented
content.

ChrisA