# PyWart: Poor Documentation Examples

Rick Johnson rantingrickjohnson at gmail.com
Sat Jan 10 19:05:06 CET 2015

```============================================================
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: