Rocksolid Light

Welcome to novaBBS (click a section below)

mail  files  register  newsreader  groups  login

Message-ID:  

SCCS, the source motel! Programs check in and never check out! -- Ken Thompson

devel / comp.lang.python / Re: Style for docstring

SubjectAuthor
* Re: Style for docstringdn
`- Re: Style for docstringStefan Ram

1
Re: Style for docstring

<mailman.265.1650938412.20749.python-list@python.org>

  copy mid

https://www.novabbs.com/devel/article-flat.php?id=18056&group=comp.lang.python#18056

  copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: PythonL...@DancesWithMice.info (dn)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Tue, 26 Apr 2022 13:59:53 +1200
Organization: DWM
Lines: 69
Message-ID: <mailman.265.1650938412.20749.python-list@python.org>
References: <2098309954.284734.1650684417423@mail.yahoo.com>
<Ymch+mSWaoXhwpj3@cskk.homeip.net>
<480a4160-41b7-7995-f38f-186f99840e5d@btinternet.com>
<a898888c-2a22-589b-c1c7-3c93abe38566@DancesWithMice.info>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de khBSb5Mh41YsIMsgqpi6OQHs/dIUk3TJf1KsNsG1IoeA==
Return-Path: <PythonList@DancesWithMice.info>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=danceswithmice.info header.i=@danceswithmice.info
header.b=F0Suxs1J; dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.003
X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'def': 0.04; 'coders':
0.05; 'description:': 0.05; 'programmer': 0.07; 'wanting': 0.07;
"'''": 0.09; '=dn': 0.09; 'from:addr:danceswithmice.info': 0.09;
'from:addr:pythonlist': 0.09; 'items.': 0.09; 'later,': 0.09;
'skip:\xc2 20': 0.09; 'cheers,': 0.11; 'avi': 0.16; 'cameron':
0.16; 'camp.': 0.16; 'coding,': 0.16; 'cognitive': 0.16;
'descriptive': 0.16; 'gross': 0.16; 'mean,': 0.16; 'message-
id:@DancesWithMice.info': 0.16; 'received:51.254': 0.16;
'received:51.254.211': 0.16; 'received:51.254.211.219': 0.16;
'received:cloud': 0.16; 'received:rangi.cloud': 0.16; 'removes':
0.16; 'sentence,': 0.16; 'separating': 0.16; 'simpson': 0.16;
'wrote:': 0.16; 'to:addr:python-list': 0.20; 'language': 0.21;
'code': 0.23; '(and': 0.25; 'opening': 0.26; "isn't": 0.27;
'function': 0.27; '>>>': 0.28; 'sense': 0.28; 'thinking': 0.28;
'header:User-Agent:1': 0.30; 'header:Organization:1': 0.31;
'think': 0.32; "doesn't": 0.32; 'gathering': 0.32; 'python-list':
0.32; 'realize': 0.32; 'but': 0.32; "i'm": 0.33; "i'll": 0.33;
'subject:for': 0.33; 'someone': 0.34; 'same': 0.34; 'requires':
0.34; 'header:In-Reply-To:1': 0.34; 'english,': 0.35;
'particularly': 0.35; 'yes,': 0.35; 'applying': 0.36; 'people':
0.36; "skip:' 10": 0.37; 'using': 0.37; 'others': 0.37;
'received:192.168': 0.37; '8bit%:14': 0.38; 'use': 0.39; 'want':
0.40; 'view': 0.60; 'provide': 0.60; 'today': 0.61; 'skip:\xc2
10': 0.62; 'mode': 0.62; 'skip:o 20': 0.63; 'skip:r 20': 0.64;
'received:51': 0.64; 'received:userid': 0.66; '8bit%:7': 0.67;
'earlier': 0.67; 'back': 0.67; 'bad': 0.67; 'items': 0.68;
'order': 0.69; 'est': 0.69; 'working,': 0.69; 'non': 0.75;
'8bit%:100': 0.76; 'produces': 0.76; 'earliest': 0.84; 'disagree':
0.84; 'rob': 0.84; 'success,': 0.84;
'\xc2\xa0\xc2\xa0\xc2\xa0\xc2\xa0': 0.84; 'question?': 0.91
DKIM-Filter: OpenDKIM Filter v2.11.0 vps.rangi.cloud 0389F3070
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=danceswithmice.info;
s=staff; t=1650938411;
bh=dvCrSTG1f9UrDtxbOqlEZ6xBYFOSlX5vWlbl5l6Ba5I=;
h=Date:Subject:To:References:From:In-Reply-To:From;
b=F0Suxs1JWzaqSKeWzHeYwvaetzmSsIgnpLIowNVzU02ZfVXKnEOIaCfVrhZ+gj9+D
L6ARA/hs6rUvGt12seZ4XNmDVVKPKJmUYb7o4r2KjP/lZ71O3u7gLx221vyuaZNDyr
hF9GuRVSL46M7/nPZ9+MTen/p12gmAY5tuNNAY87YSnZLDmTctuvtAgXBD+iLxO7l7
/9kdsRuXlKZUYVaq23Y/nYG9x8prR4CRLAZtUvYKMGbwJv7fAshUBVJ84pJ/73tQnw
traWRF5tNtoFM6ELS6sklTNP6qLiSq7UwwwSXnTWK2lqdmEAPKehbInZsGKVWauFCC
AUoNP2vbm3j+w==
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on vps517507.ovh.net
X-Spam-Level:
X-Spam-Status: No, score=-4.9 required=5.0 tests=ALL_TRUSTED,BAYES_00,
DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,NICE_REPLY_A autolearn=ham
autolearn_force=no version=3.4.0
DKIM-Filter: OpenDKIM Filter v2.11.0 vps.rangi.cloud 15F821344
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=danceswithmice.info;
s=staff; t=1650938408;
bh=dvCrSTG1f9UrDtxbOqlEZ6xBYFOSlX5vWlbl5l6Ba5I=;
h=Date:Subject:To:References:From:In-Reply-To:From;
b=F4uNkjbqWxGmcWDy4hgHu4Z95/tT8Hrw94mW+StbV4+bGRXB5y3i8hOo7Rl+SQnZT
DCM/m/g6PWEPk8dU7xhrYzPDutJg04INchVE8qhJI90Of9wqWlTYfH+5KjFYpGGTur
+Idsk45ksoRNjFUMhjYU8AGbTplTAxsYh7fLodu3xsMy3KYT9PueidXpy6jpx8TwXE
4craOnKG8MDU4oj6rVH54NisMsBO96ZjEDlrqHEpm4phMGvOoanLtaQ9WCf2l6hDR3
uW56Q0802DZhuyqYL4b6s7Gou8HyFPEWORyOoSdpLCczRg2Cu/ZVD/ExXz7oY+o88p
9Bpz3icDqaq8Q==
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
Thunderbird/91.8.1
Content-Language: en-GB
In-Reply-To: <480a4160-41b7-7995-f38f-186f99840e5d@btinternet.com>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
Precedence: list
List-Id: General discussion list for the Python programming language
<python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>,
<mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <https://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: <https://mail.python.org/mailman/listinfo/python-list>,
<mailto:python-list-request@python.org?subject=subscribe>
X-Mailman-Original-Message-ID: <a898888c-2a22-589b-c1c7-3c93abe38566@DancesWithMice.info>
X-Mailman-Original-References: <2098309954.284734.1650684417423@mail.yahoo.com>
<Ymch+mSWaoXhwpj3@cskk.homeip.net>
<480a4160-41b7-7995-f38f-186f99840e5d@btinternet.com>
 by: dn - Tue, 26 Apr 2022 01:59 UTC

On 26/04/2022 11.47, Rob Cliffe via Python-list wrote:
> Well, de gustibus non est disputandum.  For me, the switch from the
> imperative mode to the descriptive mode produces a mild cognitive
> dissonance.

Disagree!

When coding, to whom?what are you talking?

When writing documentation - same question?

This is the reason why (typically) coders are pretty bad at, or disagree
with a need for, 'documentation' - and particularly documentation that
doesn't fit inside a code-module!

(no insult, pure observation)

See earlier when I described taking a set of Requirements and
progressively applying specific clauses or requirements to a function.
One's thinking is in requirement-satisfaction-mode or 'design-mode'.
Later, when implementing the function, one can work in 'coding-mode'.

Separating tasks/roles removes the dissonance. No split-personality
required!

However, I know what you mean, and earlier today was writing to someone
about why I may not bother with a docstring if I'm in coding-mode and
wanting to 'keep going'. However, I see such as 'technical debt',
justified only in the hope that when I do get back to it (presumably
when the code is working, and I'm basking in the joys of (my own)
success, I'll be in more of a 'documentation' frame of mind...

(and pigs might fly!)

> On 25/04/2022 23:34, Cameron Simpson wrote:
>> On 23Apr2022 03:26, Avi Gross <avigross@verizon.net> wrote:
>>> We know some people using "professional" language make things shorteror
>>> talk from a point of view different than others and often in
>>> otherwise incomprehensible jargon.
>>> If a programmer is taking about the algorithm that a function
>>> implements, then, yes, they may write "scan" and "return".
>>> But if they realize the darn documentation is for PEOPLE asking
>>> how to use the darn thing, and want to write in more informal
>>> and understandable English, I think it makes more sense to say
>>> what the function does as in "scans" and importantly what it
>>> "returns" to the user as a result.
>> I'm in the imperative camp. But if I think the function requires some
>> elaboration, _then_ I provide description:
>>
>>      def f(x):
>>          ''' Return the frobnangle of `x`.
>>
>>              This iterates over the internals of `x` in blah order
>>              gathering the earliest items which are frobby and composes a
>>              nangle of the items.
>>          '''
>>
>> I very much like the concise imperative opening sentence, sometimes 2
>> sentences. Then the elaboration if the function isn't trivially obvious.
>>
>> Cheers,
>> Cameron Simpson <cs@cskk.id.au>
>

--
Regards,
=dn

Re: Style for docstring

<dissonance-20220426030547@ram.dialup.fu-berlin.de>

  copy mid

https://www.novabbs.com/devel/article-flat.php?id=18057&group=comp.lang.python#18057

  copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: ram...@zedat.fu-berlin.de (Stefan Ram)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: 26 Apr 2022 02:09:17 GMT
Organization: Stefan Ram
Lines: 17
Expires: 1 Apr 2023 11:59:58 GMT
Message-ID: <dissonance-20220426030547@ram.dialup.fu-berlin.de>
References: <mailman.265.1650938412.20749.python-list@python.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de j4lrYt4dhSboEkc5HQ7/9gjo49xZsQ8DMVAgtycRZ1Cbp9
X-Copyright: (C) Copyright 2022 Stefan Ram. All rights reserved.
Distribution through any means other than regular usenet
channels is forbidden. It is forbidden to publish this
article in the Web, to change URIs of this article into links,
and to transfer the body without this notice, but quotations
of parts in other Usenet posts are allowed.
X-No-Archive: Yes
Archive: no
X-No-Archive-Readme: "X-No-Archive" is set, because this prevents some
services to mirror the article in the web. But the article may
be kept on a Usenet archive server with only NNTP access.
X-No-Html: yes
Content-Language: en-US
Accept-Language: de-DE, en-US, it, fr-FR
 by: Stefan Ram - Tue, 26 Apr 2022 02:09 UTC

dn <PythonList@DancesWithMice.info> writes:
>On 26/04/2022 11.47, Rob Cliffe via Python-list wrote:
>>Well, de gustibus non est disputandum.  For me, the switch from the
>>imperative mode to the descriptive mode produces a mild cognitive
>>dissonance.
>Disagree!

You know better than Rob himself what produces a mild
cognitive dissonance for him?

>Separating tasks/roles removes the dissonance. No split-personality
>required!

The phenomenon of cognitive dissonance does not have
much to do with split personalities.

1
server_pubkey.txt

rocksolid light 0.9.8
clearnet tor