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 <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> > -- Regards, =dn -- https://mail.python.org/mailman/listinfo/python-list
