Your first function

Picture a recipe card. A recipe is written down once, and you cook from it as often as you like: for two people today, for ten tomorrow. The card says what to put in, what to do with it and what dish comes out at the end.

In a program, such a card is a function of your own. When the same calculation is needed in several places, it is written once and given a name. The function add takes two numbers and returns their sum:

def add(a, b):
    return a + b


print(add(2, 3))  # 5
print(add(10, -4))  # 6

Here the recipe takes the first two lines and is cooked twice: with 2 and 3, then with 10 and -4.

Definition and call

Let's take the function add apart piece by piece.

The def line

The line def add(a, b): starts a function definition. It is built like this:

1. The word def says that a new function follows.
2. add is its name, which is used to call it.
3. The parentheses list the input data a and b.
4. The colon opens a block—the function body, shifted by 4 spaces.

After a function definition, PEP 8, the commonly accepted rules for formatting Python code, asks for two blank lines.

Parameters and arguments

The parentheses after the name hold the parameters—names that receive values when the function is called. In the call add(2, 3), the arguments 2 and 3 go into the parameters a and b in order. The number of arguments must match the number of parameters.

Interviewers like to ask how a parameter differs from an argument. A parameter is a name in the function definition, and an argument is a value passed in the call.

The word return

The word return ends the function and returns the value of the expression after it. An expression is code that produces a value, such as a + b. The call itself is replaced by the returned value, so it can be passed to print.

The function add prints nothing by itself. It returns a value to the place of the call, and the value is printed by the print that holds the call.

When the body runs

The def line only creates the function, and its body runs on every call. The file runs from top to bottom, so the definition must stand above the first call. If you call a function before the interpreter has reached it, the program stops at that call with a NameError.

This is where the recipe analogy stops working. A cook can look at any page of a cookbook, even the last one. The interpreter knows only the functions whose def lines it has already run.

Click "Next step" and watch when the interpreter enters the body of add and on which line the program stops.

The program printed start and 5, then stopped with the error NameError: name 'double' is not defined. The lines below the seventh did not run, so the function double was never created. Move its definition above the call, and the program prints 8 as well.

Order of evaluation

Numbers work with the operators +, - and *; * means multiplication. As in math, * goes before + and -, and parentheses change that order. A function call can also be an argument of another call. Then the inner call runs first, and its result goes into the outer one.

print(1 + 2 * 3)  # 7
print((1 + 2) * 3)  # 9
print(add(add(1, 2), 3))  # 6
print(add(1, 2) * 10)  # 30

Let's take the last two lines apart:

1. In the third line add(1, 2) returns 3, then add(3, 3) returns 6, and only 6 is printed.
2. In the fourth line the call also runs first: add(1, 2) gives 3, and only then 3 * 10 gives 30.

Common mistake

The function body is written without an indent:

def add(a, b):
return a + b  # ✗

IndentationError: expected an indented block after function definition on line 1

After a line ending in a colon, the interpreter expects a block shifted to the right. But the next line starts at the first character. The check of the file finds the error, so the program runs none of its lines. The fix is to shift return a + b by 4 spaces, as in the first example.

Key points

• def with a name, parameters and a colon creates a function, and its body runs on every call.
• A parameter is a name in the definition, an argument is a value in the call.
• return gives back a value, and it takes the place of the call.
• The definition must stand above the first call: otherwise the program stops at the call with a NameError.