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 <avigr...@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 <c...@cskk.id.au>
--
https://mail.python.org/mailman/listinfo/python-list
