Chapter 4. Functions, Scoping, and Abstraction 41

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.