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