Organisation of python classes and their methods

[Robert Kern]

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 <breamoreboy at 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