On 4/25/22 16:34, Cameron Simpson wrote:
> On 23Apr2022 03:26, Avi Gross <avigr...@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.""").
--
https://mail.python.org/mailman/listinfo/python-list
