Rocksolid Light

Welcome to novaBBS (click a section below)

mail  files  register  newsreader  groups  login

Message-ID:  

Logic is a little bird, sitting in a tree; that smells *_____awful*.

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

SubjectAuthor
o Re: Style for docstringCameron Simpson

1
Re: Style for docstring

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

  copy mid

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

  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: Sat, 23 Apr 2022 10:23:09 +1000
Lines: 41
Message-ID: <mailman.206.1650673802.20749.python-list@python.org>
References: <YmMqqecSN67EM3Dg@scrozzle>
<YmNG7ZKSFuqdyzOB@cskk.homeip.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: news.uni-berlin.de m0/BpjUedYVDfsItsHGTyQzv2a5QlEkMpJM084U1FRDQ==
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.022
X-Spam-Evidence: '*H*': 0.96; '*S*': 0.00; 'def': 0.04; 'tests': 0.07;
'choice.': 0.09; 'dan': 0.09; 'skip:` 10': 0.09; 'cameron': 0.16;
'database,': 0.16; 'explicit': 0.16; 'from:addr:cs': 0.16;
'from:addr:cskk.id.au': 0.16; 'from:name:cameron simpson': 0.16;
'message-id:@cskk.homeip.net': 0.16; 'received:13.237': 0.16;
'received:13.237.201': 0.16; 'received:13.237.201.189': 0.16;
'received:cskk.id.au': 0.16; 'received:id.au': 0.16;
'received:mail.cskk.id.au': 0.16; 'sensible': 0.16; 'simpson':
0.16; 'wrote:': 0.16; 'calls': 0.19; 'to:addr:python-list': 0.20;
'option': 0.20; 'input': 0.21; "i've": 0.22; 'returns': 0.22;
'(and': 0.25; 'stuff': 0.25; 'perform': 0.26; 'leave': 0.27;
'function': 0.27; 'error': 0.29; 'header:User-Agent:1': 0.30;
'raise': 0.31; 'think': 0.32; 'programmers': 0.32; 'but': 0.32;
"i'm": 0.33; 'subject:for': 0.33; 'there': 0.33; 'skip:" 20':
0.34; 'header:In-Reply-To:1': 0.34; 'received:au': 0.35; 'yes,':
0.35; 'functions': 0.36; 'those': 0.36; 'this.': 0.37; 'though':
0.37; 'two': 0.39; 'valid': 0.39; 'both': 0.40; 'something': 0.40;
'want': 0.40; 'seen': 0.62; 'simply': 0.63; 'imagine': 0.64;
'received:13': 0.64; 'well': 0.65; 'named': 0.65;
'received:userid': 0.66; 'smart': 0.67; 'latter': 0.69;
'depending': 0.70; 'cheers': 0.76; 'happens': 0.84; 'choice,':
0.84; 'flavors': 0.84; 'full,': 0.84; 'invalid.': 0.84; 'minds':
0.84; 'moon': 0.84; 'wednesday': 0.91
Mail-Followup-To: python-list@python.org
Content-Disposition: inline
In-Reply-To: <YmMqqecSN67EM3Dg@scrozzle>
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: <YmNG7ZKSFuqdyzOB@cskk.homeip.net>
X-Mailman-Original-References: <YmMqqecSN67EM3Dg@scrozzle>
 by: Cameron Simpson - Sat, 23 Apr 2022 00:23 UTC

On 22Apr2022 17:22, Dan Sommers <2QdxY4RzWzUUiLuE@potatochowder.com> wrote:
>"Test whether a permutation is even," while technically factual, leaves
>the reader to wonder what form the result takes, and what happens to
>that result. Yes, we'd all like to think that programmers are smart
>enough to *assume* that the function returns the result of the test.
>I've also seen functions that perform tests and then print the results
>out, or write them to a database, or simply execute the tests for their
>side effects (or leave it up to the individual tests to do something
>with the result).

Yeah, this.

I've got lots of "test and return a Boolean" functions named
"is_something" and some "test and raise value error if bad" functions
named "validate_something". Those latter are so that I can concisely
write stuff like:

def foo(bah):
validate_bahlike(bah)
... do stuff with bah ...

to get a sensible ValueError from foo() if bah is invalid. (And
validate_something() often calls is_something() when I want both flavors
depending on circumstance.)

So I also like option 3, though I also usually write it imperatively:

Return `True` if `permutation` is even, `False` otherwise.

I'm in two minds about "otherwise" rather than being explicit about the
dual of the test. Usually "otherwise" is my choice, but I can imagine
being more explicit if there were some third (probably invalid) input
choice.

"Otherwise" also works well when there are a few valid choices:

Return `True` if the weekday is Wednesday or the moon is full,
`False` otherwise.

Cheers
Cameron Simpson <cs@cskk.id.au>

1
server_pubkey.txt

rocksolid light 0.9.8
clearnet tor