Style for docstring

[dn]

On 26/04/2022 11.47, Rob Cliffe via Python-list wrote:
> Well, de gustibus non est disputandum.  For me, the switch from the
> imperative mode to the descriptive mode produces a mild cognitive
> dissonance.

Disagree!

When coding, to whom?what are you talking?

When writing documentation - same question?

This is the reason why (typically) coders are pretty bad at, or disagree
with a need for, 'documentation' - and particularly documentation that
doesn't fit inside a code-module!

(no insult, pure observation)

See earlier when I described taking a set of Requirements and
progressively applying specific clauses or requirements to a function.
One's thinking is in requirement-satisfaction-mode or 'design-mode'.
Later, when implementing the function, one can work in 'coding-mode'.

Separating tasks/roles removes the dissonance. No split-personality
required!

However, I know what you mean, and earlier today was writing to someone
about why I may not bother with a docstring if I'm in coding-mode and
wanting to 'keep going'. However, I see such as 'technical debt',
justified only in the hope that when I do get back to it (presumably
when the code is working, and I'm basking in the joys of (my own)
success, I'll be in more of a 'documentation' frame of mind...

(and pigs might fly!)



> 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>
> 

-- 
Regards,
=dn