On Sat, 23 Apr 2022 at 09:31, Rob Cliffe via Python-list <python-list@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 -- https://mail.python.org/mailman/listinfo/python-list
