On 2022-04-23 00:25, Rob Cliffe via Python-list wrote:
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?
Maybe it's because the function name is often also an imperative, e.g.:
>>> import re
>>> help(re.search)
Help on function search in module re:
search(pattern, string, flags=0)
Scan through string looking for a match to the pattern, returning
a Match object, or None if no match was found.
Note "Scan", not "scans".
I was going to use 'print' as the example:
>>> help(print)
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
but it says "Prints", not "Print"...
--
https://mail.python.org/mailman/listinfo/python-list
