PyWart: Poor Documentation Examples

[Rustom Mody]

On Sunday, January 11, 2015 at 8:02:50 AM UTC+5:30, Steven D'Aprano wrote:
> Rick Johnson wrote:
> 
> 
> > ============================================================
> > EXAMPLE 1: "Reducing Comprehension"
> > https://docs.python.org/2/howto/doanddont.html#using-the-batteries
> > ============================================================
> > 
> > 
> >     ############################################################
> >     #                    QUOTE: Python Docs                    #
> >     ############################################################
> >     # Another highly useful function is reduce() which can be  #
> >     # used to repeatly apply a binary operation to a sequence, #
> >     # reducing it to a single value. For example, compute a    #
> >     # factorial with a series of multiply operations:          #
> >     #                                                          #
> >     # py> n = 4                                                #
> >     # py> import operator                                      #
> >     # py> reduce(operator.mul, range(1, n+1))                  #
> >     # 24                                                       #
> >     ############################################################
> 
> > How exactly does: assigning variables(n = 4),
> > arithmetic(n+1), and the "range" function going to help me
> > understand the usefulness of the reduce function?
> 
> Obviously they don't, duh. They're mere incidentals.
> 
> 
> > A much better example would be:
> > 
> >     py> import operator
> >     py> reduce(operator.mul, [1,2,3,4])
> >     24
> 
> "But Rick, my o-so-wise teacher, what's this stuff with the square brackets
> and commas? And the round brackets (or parentheses as the Americans call
> them)?"
> 
> At the point you are demonstrating reduce(), if the reader doesn't
> understand or can't guess the meaning of "n = 4", "n+1" or range(), they
> won't understand anything you say.
> 
> Teachers need to understand that education is a process of building upon
> that which has come before. If the teacher talks down to the student by
> assuming that the student knows nothing, and tries to go back to first
> principles for every little thing, they will never get anywhere.
> 
> In this case, it is perfectly acceptable to assume that by the time the
> beginner gets to a document about "Dos and Don'ts" they are comfortable
> with such basic concepts as assigning values to variables "n=4",
> addition "n+1", importing, and can interpret from the context that
> operator.mul multiplies without needing to be explicitly told.
> 
> If you treat your readers as idiots, only idiots will read your writing.
> 
> 
> > At *LEAST* with that example the only potential unknown
> > might be "operator.mul". However, a wise teacher would
> > recognize that this is a fine "teaching example" of how
> > using the operator module can prevent duplicating code --
> 
> And the version on the docs demonstrates this by example, instead of
> patronising the reader and treating them as an eight year old who needs to
> have the most trivial things explained to them.
> 
> 
> > which would lead to a better example like:
> > 
> >     py> def mul(x, y):
> >     ...     return x*y
> >     py> reduce(mul, [1,2,3,4])
> >     24
> 
> "But Rick, my o-so-wise teacher! What is the meaning of 'def', 'return' and
> the asterisk between the x and y? What's with the three dots and the
> spaces?"
> 
> 
> 
> > FINALLY! An example that showcases a proper usage of the
> > the reduce function *WITHOUT* any superfluous distractions.
> 
> Apart from having to define your own function. Given that this is a document
> intended to show-case best practice (as in Do this, Don't do that) it is
> completely inappropriate to encourage the reader to re-invent the wheel by
> creating their own (slow) mul function instead of importing the (fast)
> pre-built one in the operator module.
> 
> 
> > However, 
> > remembering that code re-use is a good thing, and that re-
> > inventing the wheel is a lot of work, we should mention that
> > the "mul" function should be replaced with "operator.mul"
> 
> No, we should not "mention" it as an aside. We should demonstrate best
> practice from the start. Unless you are writing for beginners who haven't
> been introduced to importing yet (in which case, why are you teaching them
> reduce() so early?) there is no benefit at all in showing people how *not*
> to do it, then jokingly give them a little nudge-nudge-wink-wink "by the
> way, this is better" aside.
> 
> 
> >     Note: Be sure to check out the "operator" module for
> >     pre-defined arithmetic functions like "operator.mul",
> >     which would "reduce" (*wink*) the above code to this:
> > 
> >     py> reduce(operator.mul, [1,2,3,4])
> >     24
> > 
> > 
> > ============================================================
> > EXAMPLE 2: "The Fibonacci Phallus Extender".
> 
> 
> And that's where I stopped reading. I'm sure it will be overflowing with
> insights of your usual quality, but I hurt myself laughing so hard at your
> wit ("ha ha, phallus, that means the D") that I simply couldn't continue.
> 
> 
> 
> -- 
> Steven

Rick:
Your style beyond irritating to just plain ridiculous.
As it happens I find your reduce example better than the given one.
Unfortunately dunno how to agree the one and not the other :-)