Chapter 4.

Functions, Scoping, and Abstraction

4.2

Specifications
Figure 4.5 defines a function, findRoot, that generalizes the bisection search we
used to find square roots in Figure 4.1. It also contains a function,
testFindRoot, that can be used to test whether or not findRoot works as
intended.
The function testFindRoot is almost as long as findRoot itself. To inexperienced
programmers, writing test functions such as this often seems to be a waste of
effort. Experienced programmers know, however, that an investment in writing
testing code often pays big dividends. It certainly beats typing test cases into
the shell over and over again during debugging (the process of finding out why a
program does not work, and then fixing it). It also forces us to think about
which tests are likely to be most illuminating.
The text between the triple quotation marks is called a docstring in Python. By
convention, Python programmers use docstrings to provide specifications of
functions. These docstrings can be accessed using the built-in function help.
If we enter the shell and type help(abs), the system will display
Help on built-in function abs in module __builtin__:
abs(...)
abs(number) -> number
Return the absolute value of the argument.

If the code in Figure 4.5 (below) has been loaded into IDLE, typing
help(findRoot) in the shell will display
Help on function findRoot in module __main__:
findRoot(x, power, epsilon)
Assumes x and epsilon int or float, power an int,
epsilon > 0 & power >= 1
Returns float y such that y**power is within epsilon of x.
If such a float does not exist, it returns None

If we type
findRoot(

in either the shell or the editor, the list of formal parameters and the first line of
the docstring will be displayed.

41