Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #32619

Re: Organisation of python classes and their methods

Show all headers | View raw

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@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

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Organisation of python classes and their methods Martin Hewitson <martinhewitson@mac.com> - 2012-11-02 07:16 +0100
  Re: Organisation of python classes and their methods Paul Rubin <no.email@nospam.invalid> - 2012-11-02 00:38 -0700
    Re: Organisation of python classes and their methods Martin Hewitson <martinhewitson@mac.com> - 2012-11-02 09:08 +0100
      Re: Organisation of python classes and their methods Ulrich Eckhardt <ulrich.eckhardt@dominolaser.com> - 2012-11-02 11:18 +0100
        Re: Organisation of python classes and their methods Martin Hewitson <martinhewitson@me.com> - 2012-11-02 15:49 +0100
        Re: Organisation of python classes and their methods Mark Lawrence <breamoreboy@yahoo.co.uk> - 2012-11-02 17:02 +0000
      Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-03 01:38 +0000
    Re: Organisation of python classes and their methods Mark Lawrence <breamoreboy@yahoo.co.uk> - 2012-11-02 08:40 +0000
      Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-02 10:20 +0000
    Re: Organisation of python classes and their methods Chris Angelico <rosuav@gmail.com> - 2012-11-02 20:15 +1100
    Re: Organisation of python classes and their methods Martin Hewitson <martinhewitson@mac.com> - 2012-11-02 09:45 +0100
    Re: Organisation of python classes and their methods Peter Otten <__peter__@web.de> - 2012-11-02 11:21 +0100
    Re: Organisation of python classes and their methods Mark Lawrence <breamoreboy@yahoo.co.uk> - 2012-11-02 10:48 +0000
    Re: Organisation of python classes and their methods Robert Kern <robert.kern@gmail.com> - 2012-11-02 10:55 +0000
    Re: Organisation of python classes and their methods Robert Kern <robert.kern@gmail.com> - 2012-11-02 11:07 +0000
  Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-03 01:06 +0000
    Re: Organisation of python classes and their methods Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2012-11-03 01:08 +0000

csiph-web