1 Docstrings. COSC 101 Lecture #14 Handout: Defining Functions, Part 4 Spring 2015

Transcription

1 Docstrings A docstring is a string at the beginning of a function that explains what the function does. A docstring explains what a function does, but not necessarily how it does it. Collectively, docstrings are the main vehicle for describing your program to another programmer: if I read only the main program (the statements at the end of the program that lie outside any function defintion) and the docstrings, I should know what your program does. A docstring is a triple-quoted string, also known as a multiline string because the triple quotes allow the string to span more than one line. It appears just below the function header and just above the function body. It has several components, as illustrated by the following example. This function even sum takes two numbers and returns True if their sum is even and False otherwise. Here is the function definition complete with a docstring: def even sum(num, num): (int, int) > bool Return True if and only if the sum of num and num is evenly divisible by. >>> even sum (, 6) True >>> even sum (7, 4) False >>> even sum (7, 3) True return ( num + num ) % == Docstring components: ) Examples. The docstring includes one or two examples of calls to the function and the expected return values. It should include an example of a standard case as well as tricky cases, if there are some. It is not always feasible to include an example. Some cases where examples are inappropriate: the function returns a complex object (such as an Image object) the function does not return anything but prints or writes to file the function is random and so its output is unpredictable ) Type contract. The type contract describes the types of the parameters and any return values. The line (int, int) > bool means that the function takes two int values and returns a bool. In general, the types of the inputs are enclosed in parentheses and the return type comes after the arrow. If the function does not return anything, then the return type is NoneType. 3) Description. Between the examples and type contract, add a description of what the function does. This description must mention each parameter by name. It should be terse and precise. of 5

2 Design recipe: steps to writing a new functions It is often recommended that programmers design a new function by following these steps in this order: ) Write part of the docstring, starting with examples, then type contract. ) Write the function header. 3) Write the description. Be sure to use each variable name in description. 4) Write the body of the function. Notice that you only write the body after you have already worked through several examples by hand. 5) Test the function. Run the module in IDLE and test the function by trying out the examples specified in the docstring. 3 Exercises Solutions are presented in class and also included in the moodle version of this handout. Solve each of these problems by writing at least one function. Follow the design recipe above.. At a pizzeria, adults order two slices, boys order three slices, and girls order one slice. Each pizza has eight slices. Write a function called num pizzas that takes three parameters representing the number of adults, boys, and girls, and returns the required number of pizzas. def num pizzas(adults, boys, girls): (int, int, int) > int Returns number of pizzas needed to feed the adults, boys and girls, given that adults eat two slices each, boys eat three slices each, and girls eat one slice each. A pizza has eight slices. >>> num pizzas (,, ) >>> num pizzas (,, ) >>> num pizzas (,, 3) slices = adults + boys 3 + girls pizzas = slices / 8 of 5

3 if slices % 8!= : # round up t o n e a r e s t whole p i z z a pizzas += return pizzas. You are driving a little too fast, and a police officer stops you. Write a function caught speeding to compute the result, encoded as an int value: =no ticket, =small ticket, =big ticket. If speed is 6 or less, the result is. If speed is between 6 and 8 inclusive, the result is. If speed is 8 or more, the result is. Unless it is your birthday on that day, your speed can be 5 higher in all cases. Your function should take two parameters: speed and a variable indicating whether or not it is your birthday. def caught speeding(speed, is birthday ): (int, bool) > int Returns a number indicating ticket value from =no ticket, = small ticket, = big ticket. If speed is 6 or less, the result is. If speed is between 6 and 8 inclusive, the result is. If speed is 8 or more, the result is. If is birthday is True, then speed can be 5 higher in all cases. >>> caught speeding (6, False) >>> caught speeding (65, False) >>> caught speeding (65, True) >>> caught speeding (85, False) >>> caught speeding (85, True) low limit = 6 high limit = 8 if is birthday: low limit += 5 high limit += 5 if speed < low limit: return elif speed < high limit: return else: 3 of 5

4 return 3. Write a program that prints the numbers from to. But for multiples of three print Fizz instead of the number and for the multiples of five print Buzz. For numbers which are multiples of both three and five print FizzBuzz. (a) Write a function fizz or buzz that takes in a single number and returns the appropriate print value for that number it should return either a number, Fizz, Buzz, or FizzBuzz. So that all return values have the same type, have it return the number as a string. (b) In the main program, call this function within a for loop over the numbers from to. def fizz or buzz (n): """ (int) > str Returns n as a string unless n is a multiple of three, five or both. If only three, then it returns "Fizz," if only five, then it returns "Buzz," if both three and five, returns " FizzBuzz" >>> fizz or buzz (3) Fizz >>> fizz or buzz (5) Buzz >>> fizz or buzz (5) FizzBuzz >>> fizz or buzz (4) 4 """ by3 = n % 3 == by5 = n % 5 == if by3 and by5: return " FizzBuzz" elif by3: return "Fizz" elif by5: return "Buzz" else: return str(n) 4 of 5

5 for i in range(, ): print fizz or buzz (i) 4. Write a function, count hi, that takes a string and returns the number of times that the string "hi" appears anywhere in the given string. def count hi(s): (str) > int Given s, return the number of times hi occurs in s. >>> count hi( hello. hi. bye. ) >>> count hi( hello. bye. ) >>> count hi( hihih ) >>> count hi( hihi. hello. hi. bye. ) 3 total = for i in range(len(s) ): # s h o r t e n range b / c c h e c k i n g i + if s[i] == h and s[i+] == i : total += return total 5 of 5