Rocksolid Light

Welcome to novaBBS (click a section below)

mail  files  register  newsreader  groups  login

Message-ID:  

War isn't a good life, but it's life. -- Kirk, "A Private Little War", stardate 4211.8


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

SubjectAuthor
o Re: Style for docstringCameron Simpson

1
Re: Style for docstring

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

  copy mid

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

  copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: cs...@cskk.id.au (Cameron Simpson)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Tue, 26 Apr 2022 08:34:34 +1000
Lines: 23
Message-ID: <mailman.260.1650926787.20749.python-list@python.org>
References: <2098309954.284734.1650684417423@mail.yahoo.com>
<Ymch+mSWaoXhwpj3@cskk.homeip.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de bn8CXYyG+k6qLcS7NK8PowPTgHU87KbeOs5gd0fzhAWg==
Return-Path: <cameron@cskk.id.au>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=none reason="no signature";
dkim-adsp=none (unprotected policy); dkim-atps=neutral
X-Spam-Status: OK 0.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'def': 0.04;
'description:': 0.05; 'programmer': 0.07; "'''": 0.09; 'items.':
0.09; 'cheers,': 0.11; 'avi': 0.16; 'cameron': 0.16; 'camp.':
0.16; 'from:addr:cs': 0.16; 'from:addr:cskk.id.au': 0.16;
'from:name:cameron simpson': 0.16; 'gross': 0.16; 'message-
id:@cskk.homeip.net': 0.16; 'received:10.10': 0.16; 'sentence,':
0.16; 'simpson': 0.16; 'skip:> 20': 0.16; 'wrote:': 0.16; 'to:addr
:python-list': 0.20; 'language': 0.21; 'to:name:python-
list@python.org': 0.24; '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; '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; 'use': 0.39; 'want': 0.40; 'view':
0.60; 'provide': 0.60; 'received:userid': 0.66; '8bit%:7': 0.67;
'header:Received:6': 0.67; 'items': 0.68; 'order': 0.69;
'earliest': 0.84
X-RG-Spam: Unknown
X-RazorGate-Vade: gggruggvucftvghtrhhoucdtuddrgedvfedruddvgddutdcutefuodetggdotefrodftvfcurfhrohhfihhlvgemucfupfevtfgpvffgnffuvffttedpqfgfvfenuceurghilhhouhhtmecugedttdenucenucfjughrpeffhffvuffkgggtugfgjggffhesthekredttderjeenucfhrhhomhepvegrmhgvrhhonhcuufhimhhpshhonhcuoegtshestghskhhkrdhiugdrrghuqeenucggtffrrghtthgvrhhnpeektdejheekfedtveevieetkeefledukefgveeltdffteeugefgtddtgeevgedvjeenucfkphepuddrudeggedrvdeftddrvdduvdenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhephhgvlhhopegsohhrghdrtghskhhkrdhhohhmvghiphdrnhgvthdpihhnvghtpedurddugeegrddvfedtrddvuddvpdhmrghilhhfrhhomheptggrmhgvrhhonhestghskhhkrdhiugdrrghupdhnsggprhgtphhtthhopedupdhrtghpthhtohepphihthhhohhnqdhlihhsthesphihthhhohhnrdhorhhg
X-RazorGate-Vade-Verdict: clean 0
X-RazorGate-Vade-Classification: clean
X-RG-VS-CLASS: clean
X-Authentication-Info: Submitted using ID cskk@bigpond.com
Mail-Followup-To: "python-list@python.org" <python-list@python.org>
Content-Disposition: inline
In-Reply-To: <2098309954.284734.1650684417423@mail.yahoo.com>
User-Agent: Mutt/2.2.1 (2022-02-19)
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: <Ymch+mSWaoXhwpj3@cskk.homeip.net>
X-Mailman-Original-References: <2098309954.284734.1650684417423@mail.yahoo.com>
 by: Cameron Simpson - Mon, 25 Apr 2022 22:34 UTC

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.8
clearnet tor