On 2014-03-03, Ben Finney <ben+pyt...@benfinney.id.au> wrote:
> Gregory Ewing <greg.ew...@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!
--
https://mail.python.org/mailman/listinfo/python-list
