Style for docstring

[Cameron Simpson]

On 22Apr2022 17:22, Dan Sommers <2QdxY4RzWzUUiLuE at 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 at cskk.id.au>