Re: Functional programming

From	Grant Edwards <invalid@invalid.invalid>
Newsgroups	comp.lang.python
Subject	Re: Functional programming
Date	2014-03-04 14:59 +0000
Organization	PANIX Public Access Internet and UNIX, NYC
Message-ID	<lf4pp7$54n$1@reader1.panix.com> (permalink)
References	(8 earlier) <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> <mailman.7673.1393885927.18130.python-list@python.org>

Show all headers | View raw

On 2014-03-03, Ben Finney <ben+python@benfinney.id.au> wrote:
> 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:

That's fine, if the comments are correct.  

I'm currently working with a library of third party code that was
internally documented like that (though in a different language, with
a slightly different comment formatting). Then they run it through
something (Doxygen?) to produce a giant .CHM file that's pretty much
useless to those of us running Linux.  It turns out it's just as well
I can't read a CHM file: the documentation in the comments is wrong
often enough that I've learned it's best to ignore it completely.
Sometimes the number of parameters and their names don't even match up
with the comments. Sometimes the "docstring" is from a completely
different function which was apparently cut/pasted and then reworked
to do something else.

After a couple decades of working in software development, I've
decided that comments like that are not correct often enough to be
useful. You've got to reverse-engineer the code if there's no such
comment.  If there _is_ a comment, you have to reverse-engineer the
code to see of the comment is accurate.

-- 
Grant Edwards               grant.b.edwards        Yow! I'm young ... I'm
                                  at               HEALTHY ... I can HIKE
                              gmail.com            THRU CAPT GROGAN'S LUMBAR
                                                   REGIONS!

Thread

Re: Functional programming Ned Batchelder <ned@nedbatchelder.com> - 2014-03-02 20:27 -0500
  Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 03:45 -0800
    Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-03 23:20 +1100
      Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 05:48 -0800
        Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 05:51 -0800
        Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-04 01:00 +1100
          Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 06:08 -0800
            Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-04 01:23 +1100
              Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 06:38 -0800
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-04 02:01 +1100
                Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 07:28 -0800
                Re: Functional programming Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-03-03 17:27 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-04 05:37 +1100
                Re: Functional programming Steven D'Aprano <steve@pearwood.info> - 2014-03-04 05:35 +0000
                Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 21:59 -0800
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-04 17:04 +1100
                Re: Functional programming Rustom Mody <rustompmody@gmail.com> - 2014-03-03 22:20 -0800
                Re: Functional programming Steven D'Aprano <steve@pearwood.info> - 2014-03-04 08:56 +0000
                Re: Functional programming Antoon Pardon <antoon.pardon@rece.vub.ac.be> - 2014-03-04 11:56 +0100
                Re: Functional programming Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-03-04 11:47 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 00:01 +1100
                OT Sine Rule [was Re: Functional programming] Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-03-04 14:25 +0000
                Re: OT Sine Rule [was Re: Functional programming] Tim Chase <python.list@tim.thechases.com> - 2014-03-04 08:37 -0600
                Re: OT Sine Rule [was Re: Functional programming] Mark Lawrence <breamoreboy@yahoo.co.uk> - 2014-03-04 14:42 +0000
                Re: OT Sine Rule [was Re: Functional programming] Chris Angelico <rosuav@gmail.com> - 2014-03-05 02:06 +1100
                Re: OT Sine Rule [was Re: Functional programming] Tim Chase <python.list@tim.thechases.com> - 2014-03-04 09:21 -0600
                Re: Functional programming Antoon Pardon <antoon.pardon@rece.vub.ac.be> - 2014-03-05 09:59 +0100
                Re: Functional programming Marko Rauhamaa <marko@pacujo.net> - 2014-03-04 21:49 +0200
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 07:01 +1100
                Re: Functional programming Marko Rauhamaa <marko@pacujo.net> - 2014-03-04 22:50 +0200
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 08:06 +1100
                Re: Functional programming Marko Rauhamaa <marko@pacujo.net> - 2014-03-04 23:21 +0200
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 08:26 +1100
                Re: Functional programming Marko Rauhamaa <marko@pacujo.net> - 2014-03-04 23:43 +0200
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 08:52 +1100
                Re: Functional programming Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2014-03-05 12:57 +1300
                Re: Functional programming Marko Rauhamaa <marko@pacujo.net> - 2014-03-05 02:11 +0200
                Re: Functional programming "BartC" <bc@freeuk.com> - 2014-03-04 13:30 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 00:47 +1100
                Re: Functional programming Mark Lawrence <breamoreboy@yahoo.co.uk> - 2014-03-04 14:05 +0000
                Re: Functional programming Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-03-04 14:55 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 02:13 +1100
                Re: Functional programming MRAB <python@mrabarnett.plus.com> - 2014-03-04 17:07 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 01:17 +1100
                Re: Functional programming Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-03-04 15:18 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 02:28 +1100
                Re: Functional programming Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-03-04 15:45 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 03:04 +1100
                Re: Functional programming Antoon Pardon <antoon.pardon@rece.vub.ac.be> - 2014-03-05 10:09 +0100
                Re: Functional programming "BartC" <bc@freeuk.com> - 2014-03-05 11:28 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-05 23:04 +1100
                Re: Functional programming Marko Rauhamaa <marko@pacujo.net> - 2014-03-05 14:11 +0200
                Re: Functional programming Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2014-03-04 11:06 +1300
                Re: Functional programming Ben Finney <ben+python@benfinney.id.au> - 2014-03-04 09:31 +1100
                Re: Functional programming Grant Edwards <invalid@invalid.invalid> - 2014-03-04 14:59 +0000
                Re: Functional programming Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-03-04 15:22 +0000
                Re: Functional programming Chris Angelico <rosuav@gmail.com> - 2014-03-04 09:42 +1100
                Re: Functional programming Ben Finney <ben+python@benfinney.id.au> - 2014-03-04 10:52 +1100
                Re: Functional programming "BartC" <bc@freeuk.com> - 2014-03-04 09:41 +0000
            Re: Functional programming 88888 Dihedral <dihedral88888@gmail.com> - 2014-03-03 16:35 -0800

csiph-web