On 11/2/12 10:48 AM, Mark Lawrence wrote:
On 02/11/2012 08:45, Martin Hewitson wrote:
On 2, Nov, 2012, at 09:40 AM, Mark Lawrence <breamore...@yahoo.co.uk> wrote:
On 02/11/2012 08:08, Martin Hewitson wrote:
Even if one takes reasonable numbers: 20 methods, each method has 20 lines
of documentation, then we immediately have 400 lines in the file before
writing a line of code. It would seem much more natural to me to have these
methods in their own file, grouped nicely in sub-directories. But it seems
this is not the python way. Sigh.
Thanks for your thoughts,
Martin
20 lines of documentation per method? As far as I'm concerned that's not a
smell, that's a stink.
Wow, I don't think I've ever been criticised before for writing too much
documentation :)
I guess we have different end users. This is not a set of classes for other
developers to use: it's a set of classes which creates a data analysis
environment for scientists to use. They are not programmers, and expect the
algorithms to be documented in detail.
Martin
You've completely missed the point. 99% of the time if you can't write down
what a method does in at most half a dozen lines, the method is screaming out to
be refactored. Rightly or wrongly you've already rejected that option, although
I suspect that rightly is nearer the mark in this case on the grounds that
practicality beats purity.
You've completely missed the context. These are not really complicated methods
doing lots of things all at once such that can be refactored to simpler methods.
The docstrings are not just glorified comments for other developers reading the
source code. They are the online documentation for non-programmer end-users who
are using the interactive prompt as an interactive data analysis environment.
Frequently, they not only have to describe what it's doing, but also introduce
the whole concept of what it's doing, why you would want to do such a thing, and
provide examples of its use. That's why they are so long. For example:
http://docs.scipy.org/doc/numpy/reference/generated/numpy.fft.fft.html
--
Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
--
http://mail.python.org/mailman/listinfo/python-list
