Style for docstring
Rob Cliffe
rob.cliffe at btinternet.com
Fri Apr 22 19:25:11 EDT 2022
I don't use docstrings much; instead I put a line or two of comments
after the `def ` line.
But my practice in such situations is as per the OP's 3rd suggestion, e.g.
# Returns True if .....
I'm curious as to why so many people prefer "Return" to "Returns".
Checking out help() on a few functions in the stdlib, they all used
"Return" or a grammatical equivalent, so this does seem to be a Python
cultural thing. But why? To me, "Returns" begins a description as to
what the function does, whereas "Return" is an imperative. But who is
it addresed to? Is a function considered to be a sentient entity that
can respond to a command? Is it an invocation to the lines of code
following the docstring: "Do this!" Might not the programmer mistakenly
think (if only for a moment) that the imperative is addressed to him?
Best wishes
Rob Cliffe
More information about the Python-list
mailing list