Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!feeder.erje.net!eu.feeder.erje.net!newsfeed.xs4all.nl!newsfeed2.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!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.000
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'python,': 0.02; 'read.': 0.03; 'url:sourceforge': 0.03; 'languages,': 0.04; 'parameters': 0.04; '"""': 0.07; 'compiler': 0.07; 'conventions': 0.07; 'indicated': 0.07; 'purpose.': 0.07; 'instances.': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'sphinx': 0.09; 'def': 0.12; '(it': 0.16; '``true``,': 0.16; 'algorithm.': 0.16; 'docstrings': 0.16; 'file-like': 0.16; 'finney': 0.16; 'herself': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'specifying': 0.16; 'subject:programming': 0.16; 'sure.': 0.16; 'language': 0.16; 'header:User-Agent:1': 0.23; 'error': 0.23; 'example.': 0.24; 'rid': 0.24; 'helpful': 0.24; 'header:X -Complaints-To:1': 0.27; 'point': 0.28; "doesn't": 0.30; 'nature': 0.30; 'styles': 0.31; 'writes:': 0.31; 'reader': 0.33; 'style': 0.33; 'used,': 0.33; 'beyond': 0.35; 'object,': 0.36; 'processed': 0.36; 'received:com.au': 0.36; 'sequence': 0.36; 'list': 0.37; 'ben': 0.38; 'to:addr:python-list': 0.38; 'functional': 0.39; 'to:addr:python.org': 0.39; 'received:org': 0.40; 'according': 0.40; 'helps': 0.61; 'new': 0.61; '*and*': 0.84; 'adopting': 0.84; 'received:125': 0.84; '\xe2\x80\xa6': 0.84
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Ben Finney <ben+python@benfinney.id.au>
Subject: Re: Functional programming
Date: Tue, 04 Mar 2014 09:31:48 +1100
References: <B512F079-4F01-4865-BEF3-07DF94F21832@gmail.com> <mailman.7612.1393810048.18130.python-list@python.org> <4c7dbc57-eef9-4582-aecd-aac13a39b45f@googlegroups.com> <mailman.7633.1393849247.18130.python-list@python.org> <3b54a279-03a1-4a81-a428-ecad6eb16036@googlegroups.com> <mailman.7641.1393855219.18130.python-list@python.org> <216bb5f4-32c4-4f86-a9f4-1b0dd37a2a81@googlegroups.com> <mailman.7644.1393856584.18130.python-list@python.org> <0129a5b9-b85f-4ad5-b5e2-bfb2a48041d5@googlegroups.com> <mailman.7647.1393858917.18130.python-list@python.org> <5314bb96$0$29985$c3e8da3$5496439d@news.astraweb.com> <bnkcn8FphikU1@mid.individual.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Gmane-NNTP-Posting-Host: vmx15867.hosting24.com.au
X-Public-Key-ID: 0xBD41714B
X-Public-Key-Fingerprint: 9CFE 12B0 791A 4267 887F  520C B7AC 2E51 BD41 714B
X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-gpg.asc
X-Post-From: Ben Finney <bignose+hates-spam@benfinney.id.au>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.4 (gnu/linux)
Cancel-Lock: sha1:QtNkT3Ioy3VrTZTkVVnWN+XAFyk=
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: <https://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: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.7673.1393885927.18130.python-list@python.org>
Lines: 46
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1393885927 news.xs4all.nl 2931 [2001:888:2000:d::a6]:46133
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:67605

Gregory Ewing <greg.ewing@canterbury.ac.nz> writes:

> Just because the compiler *can* infer the return type doesn't
> necessarily mean it *should*. When I was playing around with
> functional languages, I ended up adopting the practice of always
> declaring the types of my functions, because it helps the *human*
> reader.

Sure. In a duck-typed language like Python, it is still helpful to the
human reader to document the *meaning* of each parameter, beyond what is
indicated by the name. We have reStructuredText and docstrings for this
purpose.

    def frobnicate(flang, splets, queeble=False):
        """ Righteously frobnicate the flang.

            :param flang: A file-like object, opened for reading.
            :param splets: A sequence of unprocessed Splet instances.
            :param queeble: If ``True``, re-vitrify the flang during
                frobnication.
            :return: A new list of processed Splet instances.

            The flang is frobnicated according to the Weebly-Ruckford
            algorithm.

            """
        for line in flang:
            …

> (It also helped the compiler produce comprehensible error messages in
> the event of a type error.)

Docstrings in the above reStructuredText field-list style will be
processed by Epydoc <URL:http://epydoc.sourceforge.net/fields.html>.

Other styles of specifying parameters in an mechanically-extractable
form are also used, by Sphinx for example. The point is, we have
docstrings, and conventions in docstrings for specifying parameters for
the human reader *and* for automated tools to read.

-- 
 \            “… Nature … is seen to do all things Herself and through |
  `\         herself of own accord, rid of all gods.” —Titus Lucretius |
_o__)                                                 Carus, c. 40 BCE |
Ben Finney