Rocksolid Light

Welcome to novaBBS (click a section below)

mail  files  register  newsreader  groups  login

Message-ID:  

Saints should always be judged guilty until they are proven innocent. -- George Orwell


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

SubjectAuthor
o Re: Style for docstringMats Wichmann

1
Re: Style for docstring

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

 copy mid

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

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: mat...@wichmann.us (Mats Wichmann)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Mon, 25 Apr 2022 17:46:47 -0600
Lines: 26
Message-ID: <mailman.263.1650930423.20749.python-list@python.org>
References: <2098309954.284734.1650684417423@mail.yahoo.com>
<Ymch+mSWaoXhwpj3@cskk.homeip.net>
<9a41cbcb-c59a-4b7c-1c67-5532563f53bd@wichmann.us>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
X-Trace: news.uni-berlin.de AOqBGnZ69qOII20W2QpdGgA9xPQkTbFgJ7JXWfbTXtCw==
Return-Path: <mats@wichmann.us>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="1024-bit key; unprotected key"
header.d=pobox.com header.i=@pobox.com header.b=E2KfQyax;
dkim-adsp=none (unprotected policy); dkim-atps=neutral
X-Spam-Status: OK 0.018
X-Spam-Evidence: '*H*': 0.96; '*S*': 0.00; 'description:': 0.05;
'programmer': 0.07; 'received:173': 0.13; 'avi': 0.16; 'cameron':
0.16; 'camp.': 0.16; 'consensus': 0.16; 'explicit': 0.16; 'gross':
0.16; 'simpson': 0.16; 'wrote:': 0.16; 'to:addr:python-list':
0.20; 'language': 0.21; 'else': 0.27; 'function': 0.27; 'sense':
0.28; 'header:User-Agent:1': 0.30; 'think': 0.32; 'point,': 0.32;
'realize': 0.32; 'but': 0.32; "i'm": 0.33; 'subject:for': 0.33;
'there': 0.33; 'requires': 0.34; 'header:In-Reply-To:1': 0.34;
'english,': 0.35; 'yes,': 0.35; 'people': 0.36; 'guide': 0.37;
'using': 0.37; 'others': 0.37; 'received:192.168': 0.37; 'use':
0.39; 'want': 0.40; 'should': 0.40; 'view': 0.60; 'provide': 0.60;
'skip:o 20': 0.63; 'skip:b 10': 0.63; '8bit%:7': 0.67
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=message-id
:date:mime-version:subject:to:references:from:in-reply-to
:content-type:content-transfer-encoding; s=sasl; bh=d8O9OvekAmL2
AuKqchtWzbQaeLZYF+WEOk0T/4CBjS4=; b=E2KfQyax7nirIr7681dLVwfgLuld
L342o9vf6qhxCXmSM9XTDpWfdPWMHe/OOnMIJL94RE2+XJB0pQzTBW9UvGLY8Yi0
RtuNzq2MXRMC3OLus5LkmSQoQmlC7vFbeNFC8WQ3CRuEyC5YK/J+MhndeIe9A0ef
Ynms/txNBJwgW8c=
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=wichmann.us;
h=message-id:date:mime-version:subject:to:references:from:in-reply-to:content-type:content-transfer-encoding;
s=2018-07.pbsmtp; bh=5bNLueG8s891RVTYTWlbtSTxB9ZYzgwwD4C552vENns=;
b=VIEasFzDgbEUjMfa0weXdU24uWUkp3oYjFDDIZr3gsfqt0EXMeH0DMpgepuhWT7oAarg3G9cVVESkdO/t3CkHdzXxqbSUNGxWbHoP7TN9xCqvWoY/3yvUbvdnTwLwAVszwJ+l6I+I7qybp24O+eRmJdE7dOfWO1YJ6p1ofVpwQI=
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
Thunderbird/91.8.0
Content-Language: en-US
In-Reply-To: <Ymch+mSWaoXhwpj3@cskk.homeip.net>
X-Pobox-Relay-ID: F96DC740-C4F1-11EC-A107-CBA7845BAAA9-81526775!pb-smtp21.pobox.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: <9a41cbcb-c59a-4b7c-1c67-5532563f53bd@wichmann.us>
X-Mailman-Original-References: <2098309954.284734.1650684417423@mail.yahoo.com>
<Ymch+mSWaoXhwpj3@cskk.homeip.net>
 by: Mats Wichmann - Mon, 25 Apr 2022 23:46 UTC

On 4/25/22 16: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:

Just as another data point, if nothing else to prove there will never be
consensus :) - Google's style guide is pretty explicit about what they
expect:

> The docstring should be descriptive-style ("""Fetches rows from a
Bigtable.""") rather than imperative-style ("""Fetch rows from a
Bigtable.""").

1
server_pubkey.txt

rocksolid light 0.9.7
clearnet tor