Style for docstring
Rob Cliffe
rob.cliffe at btinternet.com
Mon Apr 25 19:47:14 EDT 2022
Well, de gustibus non est disputandum. For me, the switch from the
imperative mode to the descriptive mode produces a mild cognitive
dissonance.
Best wishes
Rob Cliffe
On 25/04/2022 23: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:
>
> def f(x):
> ''' Return the frobnangle of `x`.
>
> This iterates over the internals of `x` in blah order
> gathering the earliest items which are frobby and composes a
> nangle of the items.
> '''
>
> I very much like the concise imperative opening sentence, sometimes 2
> sentences. Then the elaboration if the function isn't trivially obvious.
>
> Cheers,
> Cameron Simpson <cs at cskk.id.au>
More information about the Python-list
mailing list