Style for docstring

[Avi Gross]

We know some people using "professional" language make things shorteror talk from a point of view different than others and often in otherwise incomprehensible jargon.
If a programmer is taking about the algorithm that a function implements, then, yes, they may write "scan" and "return".
But if they realize the darn documentation is for PEOPLE asking how to use the darn thing, and want to write in more informal and understandable English, I think it makes more sense to say what the function does as in "scans" and importantly what it "returns" to the user as a result.
So if you are taking a programming course and the instructor or textbook is giving imperitave commands, they may well tell youto scan something then calculate something and use a return statement a certain way.
I can read many ways and am not particularly bothered by either style but when documenting what is, I prefer proper English (or any otherlanguage) in communicating what it does for them.
As with many such things, if you work for a company or with groups of others, it is wise to find out what is expected and do the same as much as reasonable.

-----Original Message-----
From: MRAB <python at mrabarnett.plus.com>
To: python-list at python.org
Sent: Fri, Apr 22, 2022 8:57 pm
Subject: Re: Style for docstring

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