Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder1.news.weretis.net!feeder.erje.net!eu.feeder.erje.net!newsfeed.xs4all.nl!newsfeed6.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
Return-Path: <python-python-list@m.gmane.org>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.001
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'lines,': 0.05; 'nicely': 0.07; 'option,': 0.07; 'rejected': 0.07; 'missed': 0.09; 'python': 0.09; 'lawrence': 0.09; 'methods,': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'subject:python': 0.11; 'file,': 0.15; 'grounds': 0.16; 'grouped': 0.16; 'programmers,': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'scientists': 0.16; 'subject:their': 0.16; 'wow,': 0.16; 'wrongly': 0.16; 'martin': 0.16; 'users.': 0.16; 'wrote:': 0.17; 'documented': 0.17; 'creates': 0.18; '>>>': 0.18; 'code.': 0.20; "i've": 0.23; 'seems': 0.23; 'header:In-Reply-To:1': 0.25; 'header :User-Agent:1': 0.26; 'developers': 0.26; 'am,': 0.27; 'guess': 0.27; 'header:X-Complaints-To:1': 0.28; 'lines': 0.28; 'environment': 0.29; "i'm": 0.29; 'classes': 0.30; 'expect': 0.31; 'file': 0.32; 'from:addr:yahoo.co.uk': 0.32; 'to:addr:python- list': 0.33; 'point.': 0.33; "can't": 0.34; 'thanks': 0.34; 'received:org': 0.36; 'but': 0.36; 'method': 0.36; 'too': 0.36; 'does': 0.37; 'far': 0.37; 'data': 0.37; 'subject:: ': 0.38; 'mark': 0.38; 'to:addr:python.org': 0.39; 'takes': 0.39; 'header:Received:5': 0.40; 'end': 0.40; 'think': 0.40; 'your': 0.60; 'most': 0.61; "you've": 0.61; 'different': 0.63; 'ever': 0.63; 'more': 0.63; 'natural': 0.65; 'detail.': 0.65; 'analysis': 0.70; 'beats': 0.84; 'dozen': 0.91; 'numbers:': 0.91; 'thoughts,': 0.91
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Mark Lawrence <breamoreboy@yahoo.co.uk>
Subject: Re: Organisation of python classes and their methods
Date: Fri, 02 Nov 2012 10:48:54 +0000
References: <mailman.3177.1351840590.27098.python-list@python.org> <7xa9v0wj2g.fsf@ruckus.brouhaha.com> <EC7A64A6-D853-4738-92FC-673877C42513@mac.com> <k700tc$4mc$1@ger.gmane.org> <D8EB7DFA-E006-4BD8-9CA3-4015B43765F2@mac.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Gmane-NNTP-Posting-Host: host-78-146-15-195.as13285.net
User-Agent: Mozilla/5.0 (Windows NT 6.0; rv:16.0) Gecko/20121026 Thunderbird/16.0.2
In-Reply-To: <D8EB7DFA-E006-4BD8-9CA3-4015B43765F2@mac.com>
X-Antivirus: avast! (VPS 121102-0, 02/11/2012), Outbound message
X-Antivirus-Status: Clean
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.3197.1351853384.27098.python-list@python.org>
Lines: 33
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1351853384 news.xs4all.nl 6959 [2001:888:2000:d::a6]:53144
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:32616

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.

-- 
Cheers.

Mark Lawrence.