Functional programming

[Grant Edwards]

On 2014-03-03, Ben Finney <ben+python at benfinney.id.au> wrote:
> Gregory Ewing <greg.ewing at 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!