Functions 0/2

Lesson 7 of 21

Designing functions

Say what a function does, check it with tests, and break a problem into functions.

Part 1 of 6 Saying what a function does

Writing down what a function does

A function you write gets called again: further down the same program, in the next problem, or by you a month from now, when you no longer remember its body. Each caller needs to know which arguments the function accepts, what it can return, and which result it gives for each argument. In this lesson we write those answers down, check that the body really keeps to them, and then split a bigger problem into functions you can trust one at a time.

We'll start with a function worth keeping. Rounding a division up takes (a + b - 1) // b: 20 items packed 12 to a box need 2 boxes, and so do 24 items. As a function, the formula becomes ceil_div(a, b), where ceil is short for ceiling, the usual name for rounding up. The name alone doesn't say whether b can be 0 or whether a can be negative, so we write the answers next to the function:

Sign up to run
def ceil_div(a, b):
    """Return a divided by b, rounded up to a whole number.

    b must be positive.
    """
    # Adding b - 1 reaches the next multiple of b only when there is a remainder.
    return (a + b - 1) // b

print(ceil_div(20, 12))
print(ceil_div(24, 12))
Python details

A string written as the first line of a function's body is its docstring. Python keeps it with the function, so help(ceil_div) prints it.

The docstring is the function's specification. It answers the caller's questions in two parts: what the function returns, which is a/ba / b rounded up, and what the caller has to supply, which is a positive b. A caller who keeps to that can rely on the answer. A caller who passes 0 for b gets no promise at all.

The line starting with # is a comment, a note for people reading the code, which Python ignores. It has a different reader from the docstring. The docstring is for whoever calls the function, and says what it does. The comment is for whoever reads or changes the body, and says why a line works. help(ceil_div) shows the docstring and leaves the comment out.

The specification says what ceil_div returns and leaves out how the body works it out. It is functional abstraction, written down. If you later replace the body with another one that returns the same values, every program that calls ceil_div keeps working, and none of them needs to be reread.

Definition

A function's specification says what the function needs from its caller and what it gives back, without saying how its body works it out.

Inputs the requirements rule out

The requirement in the docstring isn't arbitrary. It rules out exactly the inputs where the body gives a wrong answer or no answer, and you can find them by trying a few. With 0 for b, the division stops the program with ZeroDivisionError. With a negative b, the answer is wrong: 7/(−3)≈−2.337 / (-3) \approx -2.33, which rounds up to −2-2, but ceil_div(7, -3) returns −1-1.

A negative a is fine, though. ceil_div(-7, 3) returns −2-2, which is −2.33-2.33 rounded up. The formula relies on // rounding down, and Python's // rounds down for negative numbers too. So the docstring asks for a positive b and lets a be any integer.