Rocksolid Light

Welcome to novaBBS (click a section below)

mail  files  register  newsreader  groups  login

Message-ID:  

The "cutting edge" is getting rather dull. -- Andy Purshottam


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

SubjectAuthor
o Re: Style for docstringRob Cliffe

1
Re: Style for docstring

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

 copy mid

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

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: rob.cli...@btinternet.com (Rob Cliffe)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Tue, 26 Apr 2022 00:47:14 +0100
Lines: 30
Message-ID: <mailman.264.1650930527.20749.python-list@python.org>
References: <2098309954.284734.1650684417423@mail.yahoo.com>
<Ymch+mSWaoXhwpj3@cskk.homeip.net>
<480a4160-41b7-7995-f38f-186f99840e5d@btinternet.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de tzx9iZXJmqu/RPFYmUNllA/srU/ufilifnAyma7s7CAg==
Return-Path: <rob.cliffe@btinternet.com>
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=btinternet.com header.i=@btinternet.com header.b=rek2jmmU;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.017
X-Spam-Evidence: '*H*': 0.97; '*S*': 0.00; 'def': 0.04;
'description:': 0.05; 'programmer': 0.07; "'''": 0.09; 'items.':
0.09; 'received:192.168.1.64': 0.09; 'cheers,': 0.11; 'avi': 0.16;
'cameron': 0.16; 'camp.': 0.16; 'cognitive': 0.16; 'descriptive':
0.16; 'gross': 0.16; 'sentence,': 0.16; 'simpson': 0.16; 'wrote:':
0.16; 'to:addr:python-list': 0.20; 'language': 0.21; 'opening':
0.26; "isn't": 0.27; 'function': 0.27; 'sense': 0.28; 'header
:User-Agent:1': 0.30; 'think': 0.32; 'gathering': 0.32; 'realize':
0.32; 'received:192.168.1': 0.32; 'but': 0.32; "i'm": 0.33;
'subject:for': 0.33; 'requires': 0.34; 'header:In-Reply-To:1':
0.34; 'english,': 0.35; 'yes,': 0.35; 'people': 0.36; 'using':
0.37; 'others': 0.37; 'received:192.168': 0.37; '8bit%:14': 0.38;
'use': 0.39; 'received:213': 0.40; 'wishes': 0.40; 'want': 0.40;
'view': 0.60; 'provide': 0.60; 'best': 0.61; 'mode': 0.62; 'skip:o
20': 0.63; '8bit%:7': 0.67; 'items': 0.68; 'order': 0.69; 'est':
0.69; 'non': 0.75; 'produces': 0.76; 'earliest': 0.84; 'rob': 0.84
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=btinternet.com;
s=btmx201904; t=1650930434;
bh=vkAsDw4Yl7S3NxwLPW2JaSRZvs7mNNphON2AeE9Djn4=;
h=Message-ID:Date:MIME-Version:Subject:To:References:From:In-Reply-To;
b=rek2jmmU+oAhaRYIvHUB6DfBtfIimQxtd/iq6TMnBrRr4EUjdEQcSDPMqTlqVY775YwiWc7AtAta/UjIIgJAyZVR0zC+psSuI48RSRE2gSDIKri6Nvgcw758kSC2Prctny/bw02czWWmeElX9/pkHXI+kgWjleoDYOFhZ4t2tk2qBs0fyvARafUkP8bw1pHU/kJCgx3RkOW7CDZBdvMDvAtQrjXsVETJJmY1WmQJIldgpwJsGjkNuXKhDCnfHxj+zv00kDy5J8kIpUU0nn0xEeb6wshJg6afY3AR2BLcKQp2AD1qbQSex+xNNSHDhqjwS1e8zTqNBYJQvvlr9DbI8w==
Authentication-Results: btinternet.com;
auth=pass (PLAIN) smtp.auth=rob.cliffe@btinternet.com;
bimi=skipped
X-SNCR-Rigid: 613943C620D51B40
X-Originating-IP: [86.141.29.3]
X-OWM-Source-IP: 86.141.29.3 (GB)
X-OWM-Env-Sender: rob.cliffe@btinternet.com
X-VadeSecure-score: verdict=clean score=0/300, class=clean
X-RazorGate-Vade: gggruggvucftvghtrhhoucdtuddrgedvfedruddvgddviecutefuodetggdotefrodftvfcurfhrohhfihhlvgemuceutffkvffkuffjvffgnffgvefqofdpqfgfvfenuceurghilhhouhhtmecufedtudenucenucfjughrpefkffggfgfuvfhfhfgjtgfgsehtkeertddtfeejnecuhfhrohhmpeftohgsucevlhhifhhfvgcuoehrohgsrdgtlhhifhhfvgessghtihhnthgvrhhnvghtrdgtohhmqeenucggtffrrghtthgvrhhnpedvteduhfetgfevgeeiffelledvuefgieekveevhedutefgveeijeeftdetvedtgeenucfkphepkeeirddugedurddvledrfeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhephhgvlhhopegludelvddrudeikedruddrieegngdpihhnvghtpeekiedrudeguddrvdelrdefpdhmrghilhhfrhhomheprhhosgdrtghlihhffhgvsegsthhinhhtvghrnhgvthdrtghomhdpnhgspghrtghpthhtohepuddprhgtphhtthhopehphihthhhonhdqlhhishhtsehphihthhhonhdrohhrgh
X-RazorGate-Vade-Verdict: clean 0
X-RazorGate-Vade-Classification: clean
X-SNCR-hdrdom: btinternet.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101
Thunderbird/91.8.1
Content-Language: en-GB
In-Reply-To: <Ymch+mSWaoXhwpj3@cskk.homeip.net>
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: <480a4160-41b7-7995-f38f-186f99840e5d@btinternet.com>
X-Mailman-Original-References: <2098309954.284734.1650684417423@mail.yahoo.com>
<Ymch+mSWaoXhwpj3@cskk.homeip.net>
 by: Rob Cliffe - Mon, 25 Apr 2022 23:47 UTC

Well, de gustibus non est disputandum.  For me, the switch from the
imperative mode to the descriptive mode produces a mild cognitive
dissonance.
Best wishes
Rob Cliffe

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>

1
server_pubkey.txt

rocksolid light 0.9.7
clearnet tor