Style for docstring

[Chris Angelico]

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