Re: Organisation of python classes and their methods

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.000
X-Spam-Evidence	'H': 1.00; 'S': 0.00; 'url:pypi': 0.03; 'processed': 0.05; 'python': 0.09; 'docstrings': 0.09; 'lawrence': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'url:sphinx': 0.09; 'subject:python': 0.11; 'programmers,': 0.16; 'received:80.91.229.3': 0.16; 'received:dip.t-dialin.net': 0.16; 'received:plane.gmane.org': 0.16; 'received:t-dialin.net': 0.16; 'scientists': 0.16; 'sphinx.': 0.16; 'subject:their': 0.16; 'wow,': 0.16; 'martin': 0.16; 'users.': 0.16; 'wrote:': 0.17; 'documented': 0.17; 'thorough': 0.17; 'creates': 0.18; "i've": 0.23; 'external': 0.24; 'header:User-Agent:1': 0.26; 'developers': 0.26; 'am,': 0.27; 'guess': 0.27; 'document.': 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; 'url:python': 0.32; 'to:addr:python-list': 0.33; 'typically': 0.33; 'received:org': 0.36; 'url:org': 0.36; 'smaller': 0.36; 'too': 0.36; 'far': 0.37; 'data': 0.37; 'subject:: ': 0.38; 'mark': 0.38; 'to:addr:python.org': 0.39; 'header:Received:5': 0.40; 'end': 0.40; 'think': 0.40; 'different': 0.63; 'ever': 0.63; 'details': 0.63; 'detail.': 0.65; 'analysis': 0.70
X-Injected-Via-Gmane	http://gmane.org/
To	python-list@python.org
From	Peter Otten <__peter__@web.de>
Subject	Re: Organisation of python classes and their methods
Date	Fri, 02 Nov 2012 11:21:58 +0100
Organization	None
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"
Content-Transfer-Encoding	7Bit
X-Gmane-NNTP-Posting-Host	p5084bc61.dip.t-dialin.net
User-Agent	KNode/4.7.3
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.3195.1351851725.27098.python-list@python.org> (permalink)
Lines	22
NNTP-Posting-Host	2001:888:2000:d::a6
X-Trace	1351851725 news.xs4all.nl 6938 [2001:888:2000:d::a6]:46355
X-Complaints-To	abuse@xs4all.nl
Xref	csiph.com comp.lang.python:32614

Show key headers only | View raw

Martin Hewitson wrote:

> On 2, Nov, 2012, at 09:40 AM, Mark Lawrence <breamoreboy@yahoo.co.uk>
> wrote:

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

While I would never discourage thorough documentation you may be better off 
with smaller docstrings and the details in an external document. Python 
projects typically use rst-files processed by sphinx.

http://pypi.python.org/pypi/Sphinx/

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