Style for docstring
dn
PythonList at DancesWithMice.info
Mon Apr 25 21:59:53 EDT 2022
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
More information about the Python-list
mailing list