Style for docstring

[dn]

On 23/04/2022 08.35, Michael F. Stemper wrote:
> On 22/04/2022 14.59, Chris Angelico wrote:
>> On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
>> <michael.stemper at gmail.com> wrote:
>>>
>>> I'm writing a function that is nearly self-documenting by its name,
>>> but still want to give it a docstring. Which of these would be
>>> best from a stylistic point of view:
>>>
>>>
>>>     Tells caller whether or not a permutation is even.
>>>
>>>     Determines if a permutation is even. (Alternative is that it's odd.)
>>>
>>>     Returns True if permutation is even, False if it is odd.
> 
> 
>>
>> I'd go with the third one, but "Return" rather than "Returns". Or
>> possibly "Test whether a permutation is even".
> 
> "So let it be written. So let it be done."
> 
>> That's just one opinion though, others may disagree :)
> 
> Two for two. Thanks.


I've always taken the PEP somewhat for granted (with belated thanks and
respect to the authors and others who exerted effort (or would that be,
efforts?) to publish the finished work.

One of the things that I've taken-as-read, is WHY we use docstrings.
That rationale is wider than Python. Like many others, I just brought
that sort thinking with me.

Have you noticed that the PEP doesn't discuss this? It has taken this
thread to make me realise such.


The elephant in the style room is PEP-008. It's quite old in
'Python-years'! As time went by, PEP-257 became relevant - and I don't
recall which was 'chicken' and which 'egg', between the PEP and the
docutils/help/etc tools which depend upon a level of docstring
uniformity. No matter, together they represent a step of progress, after
PEP-008.

Since then we have added typing. Where once there was an extensive
documentation system to clarify the use of parameters and the definition
of return-values, now much of that can be done on the def-line (or
equivalent).

Another 'development' (I'd prefer 'natural progression') is that as
computers have become more powerful and storage cheaper, we have been
able to first justify, and now habitually, use longer identifier-names.
This step of progress should enable more descriptive and readable code.


So, we can consider that there are (now) three aspects which overlap,
considerably:

1 the name of the function
- descriptive and readable (see OP's assurance on this point)
2 typing
- description and distinction of parameters and return-values
3 docstring
- even more information about the function, how the author intends it be
used, embedded assumptions, etc

Thus, aren't there situations where a short, sharp, DRY, and SRP,
function; once well-named and accurately typed, could stand on its own
merits without a docstring. (yes, others will suck in their breath and
start preparing a bon-fire, at the utterance of such 'heresy'...)

We all hate 'boiler-plate', ie feeling forced to type stuff 'just
because', and particularly when it seems like duplication/repetition
(see recent thread(s) 'here' about __init__() and dataclasses). In fact,
one reason why we have functions is to reduce/remove (code) duplication!
So, why would we indulge in documental 'duplication' just-because we
should?must have a docstring?


While I'm tilting at windmills, wasn't option-2 the best?
(ooh, those flames are starting to warm my feet...)

Why? First, see other discussion about "imperatives".

My habit is to take the Statement of Requirements and copy it into a
brand-new __main__. As development proceeds, various details will be
extracted and copied into function and class docstrings. The language of
a specification should be imperative, ie you will *do* 'this'.

A second reason, is that the docstring should document the function,
which is subtly-different from describing the return-value (and that has
become a task for typing anyway).
(OK, the flames are getting-good, and it's time to break-out the
marsh-mallows and crumpets...)

So, 'nr2' describes what the function DOES!


PS would you mind passing-over the fire-extinguisher?
-- 
Regards,
=dn