PyWart: Poor Documentation Examples

[Rick Johnson]

============================================================
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                                                       #
    ############################################################


Ignoring the obvious mis-spellings @_ at ...

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? A much
better example would be:

    py> import operator
    py> reduce(operator.mul, [1,2,3,4])
    24

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 --
which would lead to a better example like:

    py> def mul(x, y):
    ...     return x*y
    py> reduce(mul, [1,2,3,4])
    24

FINALLY! An example that showcases a proper usage of the
the reduce function *WITHOUT* any superfluous distractions. 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"

    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".
https://docs.python.org/2/tutorial/controlflow.html#defining-functions
============================================================

    #########################################################
    #                   QUOTE: Python Docs                  #
    #########################################################
    # We can create a function that writes the Fibonacci    #
    # series to an arbitrary boundary:                      #
    #                                                       #
    # py> def fib(n):    # write Fibonacci series up to n   #
    # ...     """Print a Fibonacci series up to n."""       #
    # ...     a, b = 0, 1                                   #
    # ...     while a < n:                                  #
    # ...         print a,                                  #
    # ...         a, b = b, a+b                             #
    # ...                                                   #
    # py> # Now call the function we just defined:          #
    # ... fib(2000)                                         #
    # 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 #
    #########################################################


No, No, *NO*! This is the most horrible example i have ever
encountered. Why would you introduction functions with an
example of calculating Fibonacci series? How are
"doc-strings" and "multiple assignment" and "loops" and
"conditions" the "print function" and "comments" going to
help me understand "defining a python function"?

Listen, if your primary goal is to teach, then *BEFORE* you
provide *ANY* examples of "defining functions", you should
*FIRST* explain what a function *IS* and *WHY* you would
want to use one.

    Next we going to learn about defining functions, but
    before we do, we need to understand *WHAT* a function
    *IS* and *WHY* we should use them ...

    [LAZY DOC WRITERS CAN INSERT EXTERNAL LINK HERE!]

Now that we've explained the *what* and *why* of functions,
we need to provide an example of the most *BASIC* of python
function definitions:

    py> def add(x, y):
        return x + y
    py> add(1,1)
    2

*SCHOOL-BELL-RINGS*