Style for docstring
Chris Angelico
rosuav at gmail.com
Fri Apr 22 19:59:13 EDT 2022
On Sat, 23 Apr 2022 at 09:31, Rob Cliffe via Python-list
<python-list at python.org> 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 .....
The point of docstrings is that they can be read by various tools.
Otherwise, they are every bit as good as comments.
> 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?
That's a very broad convention; for instance, git commit messages are
conventionally written imperatively, too. You can think of a commit
message as "If applied, this patch will blah blah blah", and a
docstring as "When called, this function will blah blah blah". Aside
from the initial capital letter, an imperative sentence will nicely
complete those descriptions.
ChrisA
More information about the Python-list
mailing list