On 23Apr2022 03:26, Avi Gross <[email protected]> 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 <[email protected]>
--
https://mail.python.org/mailman/listinfo/python-list
