PyWart: Poor Documentation Examples

[Steven D'Aprano]

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