Style for docstring
Mats Wichmann
mats at wichmann.us
Mon Apr 25 19:46:47 EDT 2022
On 4/25/22 16:34, Cameron Simpson wrote:
> On 23Apr2022 03:26, Avi Gross <avigross at verizon.net> wrote:
>> 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.
>
> I'm in the imperative camp. But if I think the function requires some
> elaboration, _then_ I provide description:
Just as another data point, if nothing else to prove there will never be
consensus :) - Google's style guide is pretty explicit about what they
expect:
> The docstring should be descriptive-style ("""Fetches rows from a
Bigtable.""") rather than imperative-style ("""Fetch rows from a
Bigtable.""").
More information about the Python-list
mailing list