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
--
https://mail.python.org/mailman/listinfo/python-list
