Style for docstring
Cameron Simpson
cs at cskk.id.au
Fri Apr 22 20:23:09 EDT 2022
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>
More information about the Python-list
mailing list