Week 4 · 41039 Programming 1

Methods, Functions and Records

Until now every program has been one long main. This week you break a program into named pieces — methods in Java, functions in Python — and learn exactly how values travel into and out of them. Along the way: what a call does in memory, why a method can change your array but not your int, and Java’s records, the tidy answer to the bundling problem that ended Weeks 2 and 3.

Code comprehension 1 · this week 3 Ed lessons Java Python

Factors.java

public static boolean isFactor(int f, int n) {
    return n % f == 0;
}

public static void printFactors(int n) {
    for (int i = 2; i <= n; ++i) {
        if (isFactor(i, n)) {
            System.out.println(i + " is a factor");
        }
    }
}

Week 4 · Interactive

The lecture, then the practice

Choose a section from the list to open it — or use the arrow keys once the list has focus. Every code example explains itself: hover over an underlined part (or tap it) to see what it does. Run runs it; ✎ Edit opens it in an editor to change it and break it on purpose. Several are meant to fail — read what the compiler says before you fix them.

01What methods are for

1.1Pieces of code with well-defined inputs

You have been calling methods since Week 1 — System.out.println(String), sc.nextInt() — so you already have some idea of the point. A method is a piece of code that takes well-defined inputs and performs some task. You write one when you spot a well-defined task your program is going to do over and over again.

That makes methods the basic unit of code reuse in Java. Because Java is object-oriented, they are also how you interact with classes and objects: a class usually has member variables, and methods mediate access to them. Put another way:

Nouns and verbs

Data are the nouns; methods are the verbs — the actions a class or object can take. And because Java is (almost) strictly object-oriented, a method must be declared inside a class. It cannot float around on its own.

Modularize. Use subroutines.

Brian W. Kernighan & P. J. Plauger, The Elements of Programming Style, 2nd ed., 1978, ch. 4 Portrait: Ben Lowe, 2012 · CC BY 2.0

“Subroutine” is the older word for the same idea. Java calls them methods, Python calls them functions, and Fortran — one of the two languages Kernighan and Plauger’s examples are written in — calls them subroutines.

Did you know?

The subroutine had to be invented. Maurice Wilkes, David Wheeler and Stanley Gill, working on Cambridge’s EDSAC, are credited with inventing the closed subroutine around 1951: one copy of the code, jumped to from anywhere, which then jumps back — the jump was long called a “Wheeler jump”. But Alan Turing had already discussed subroutines in his 1945 design proposal for the NPL ACE, going so far as to invent a stack of return addresses — the idea behind section 6. Source: Wikipedia — Function (computer programming), History and David Wheeler (computer scientist).

EDSAC under construction at Cambridge: tall racks of valves and wiring — Photo: Computer Laboratory, University of Cambridge, reproduced by permission · CC BY 2.0

1.2The method header, in five parts

The syntax for declaring a method is possibly the single most complicated piece of syntax in Java, mostly because several parts are optional. A minimal selection to start with — this line is the method’s header (or signature), followed by a block of code in braces:

<access modifier> [static] <return type> <name>(<parameter list>) {
    <code>
}

Part	What it does
access modifier	Who may call it. For now just two: `public` — any part of the program; `private` — only the class that contains it (and objects of that class)
[static]	Optional (that is what the square brackets mean). Makes the method available from the class, so it can be called without creating an object first
return type	The type of the value the method gives back when it is done — or `void` if it gives back nothing
name	Same rules and style as a variable: start lowercase, capitalise each later word, and make it say what the method does — usually a verb or a question: `printFactors`, `isFactor`
parameter list	A comma-separated list that defines the data passed in. Each entry looks like a variable declaration — because effectively it is one

A concrete example. Enter two numbers:

Both add and main are declared between the braces of Add. Java has no free-standing functions: every method belongs to some class.
The first part of the header. private lets only code inside Add call the method; main is inside Add, so it may.
The method can be called with no object in existence. main is static and runs before any object exists, which is why it can simply write add(n, m).
Every call to add produces an int, so a call can be used anywhere an int value can — here, as the argument to println.
Two parameters, each declared like a variable. a and b exist only inside add, and are created afresh on every call with the values the caller passes in.
return ends the method and gives the value of a + b to the caller. That value is an int, as the header promised.
nextInt reads the next whole number typed in and returns it as an int, which is stored in n. With the input 3 4, n gets 3 and m gets 4.
The arguments are matched to the parameters by position: the value of n is copied into a, m into b. Java runs this inner call first, and println receives the int it returns.

Read the header private static int add(int a, int b) against the table: private, so only Add can use it; static, so main can call it without creating an object; it returns an int; it is called add; and it takes two ints that will be called a and b inside the method — regardless of what they were called outside. Here the caller’s variables are n and m.

1.3`main`, read the same way

You have typed public static void main(String[] args) since Week 1. Now it can be read part by part:

public — any part of the program can call it.
static — it runs right at the start, when no objects exist yet, so it has to be static.
void — it returns nothing.
main — its name.
String[] args — one parameter, an array of Strings holding the command-line arguments given to the program, if any.

1.4Without `static`

To see what static is buying you, take it away. The method now belongs to objects of the class, so main has to make one first and call the method on it — the same new you use for a Scanner:

The same header without static. The method now belongs to each object of class Add, so it can only be called on an object.
main runs when no object exists yet, so it has no object to call add on. It must make one before it can use the method.
nextInt is a non-static method of Scanner, which is why you have always called it on an object, sc, rather than on its own.
The class Add can be the type of a variable, just as Scanner is the type of sc. adder will refer to an Add object.
new builds an object of class Add and gives back a reference to it. Add has no member variables, so this object holds no data; it exists only so that add can be called on it.
The object.method(arguments) form, as in sc.nextInt(). The parameters and the returned int work exactly as in the static version, so the program prints the same sum.

Forget the object and call it the old way, and the compiler stops you. Run this one and read the message:

The instance method from 1.4: it belongs to objects of Add, so every call needs an object to be called on.
Nothing in the body of add is wrong. The compiler objects only to the way main calls it.
Inside a static method there is no current object. main belongs to the class and runs before any Add object has been created.
A bare call to a non-static method from static main: there is no object to call it on, so the program does not compile. Fix it by putting static back on line 3 (as in 1.2), or by calling new Add().add(3, 4) (as in 1.4).

The console here says Cannot make a static reference to the non-static method add(int, int); Ed’s javac says non-static method add(int,int) cannot be referenced from a static context. Same complaint: main is static, and there is no object to call add on. Until the classes weeks, make your methods static.

1.5A typical first program with methods, explained

Measuring a flat: three small methods, each with one well-defined task, called again and again from main. Every header has the five parts from 1.2, and the return types cover all three cases — a number, a yes/no answer, and nothing. Point at an underlined part to see what it does, then press Run.

The access modifier. main is inside Flat, so it can call area; code in any other class that tries Flat.area(3, 4) will not compile.
main is static too, so it can call area directly, with no new Flat() first. Leave static off and every call from main fails with Cannot make a static reference to the non-static method.
Two inputs, each written like a variable declaration — because each one is: width and length are variables that exist only inside area.
Ends the method and gives the product to whoever called it. Its type must match the int in the header.
The return type is boolean and the name asks a yes/no question, so if (isLarge(a)) reads like English. Line 8 returns the comparison itself: true or false.
printRoom’s whole job is printing, so there is no value to return. Its calls stand alone as statements; int x = printRoom("Study", 2, 3); would not compile.
The caller’s w and l are matched to width and length by position, not by name. Inside area only the parameter names exist.
public, static (it runs before any object exists), void, the name main, and one parameter: an array of the command-line arguments, unused here.
The printing task is written once and used for three rooms, each call with its own inputs. A fourth room would cost one more line.

02Return values and `return`

2.1Getting information out

The return value is the primary tool for getting information out of a method. A method can change values outside itself, but that is not a good way of passing information around. Some methods exist precisely to change things; those typically have return type void. Normally a Java method either returns a value or modifies something — not both. There are always exceptions.

Exactly one value

A Java method returns a single value. It may be a complicated one — an array, an object holding its own data — but it comes back as one thing. If you have written a method that needs to return two separate things, you may be writing the wrong method: break the problem down further, or work out why the two belong together and put them together. Section 8.5 shows the neatest way to do that.

2.2The `return` statement

A method whose return type is not void must have at least one provably reachable return statement. return is where the value is produced, the method ends, and control — together with the value — goes back to whatever code called it. The value must have the declared return type.

The type written before the method name is what every call hands back: here exactly one boolean, true or false. Any type can go there, or void for none.
n % f is the remainder when n is divided by f, which is 0 exactly when f divides n. % is worked out before ==, so the whole expression is a boolean — the declared type — and return sends it back to the caller.
This method’s job is to print, not to work something out, so it returns nothing. It needs no return: it simply ends at its closing brace and control goes back to the caller.
Arguments are matched by position: i becomes f and n becomes n. The boolean that isFactor returns takes the call’s place as the if condition.
nextInt() has return type int: it reads the next whole number typed and hands it back, and = stores that value in n.
With no value returned, the call can only be a statement on its own. For 12 the loop tries every i from 2 to 12 and prints the five that divide it, 12 itself included.

isFactor(int, int) returns a boolean, and whatever input it is given, its return is reached.
printFactors and main are void, so they need no return at all.

Notice that isFactor returns the comparison itself. Weeks 2+3 said a whole expression has a type and can go anywhere a value of that type is expected — including straight after return. No if (…) return true; else return false; needed.

2.3Three ways to get it wrong

Return the wrong type and you get the old incompatible types error — n % f is an int, not a boolean:

The return type says every call hands back a boolean, so the compiler checks each return in the body against it.
The value after return must have the declared type, or one Java converts to it automatically — an int would do in a double method. No number converts to boolean.
The remainder of two ints is an int, and Java never treats a number as true or false. ECJ reports Type mismatch: cannot convert from int to boolean; Ed’s javac says incompatible types: int cannot be converted to boolean.
A compile error stops the whole program, so this call never happens. Write return n % f == 0; and the method compiles, returning true for 3 and 12.

Forget the return altogether and the compiler notices:

The return type is not void, so every way through the method must end at a return carrying a boolean.
The compiler ignores comments, so this body is empty and contains no return at all.
Control would reach this closing brace with no value to hand back, and the compiler rejects that. ECJ underlines the method’s name: This method must return a result of type boolean; Ed’s javac points at this brace: missing return statement.
println needs the value this call returns, and there would be none — which is why the check happens before anything runs. A void method needs no return, but then it could not be used here at all.

The interesting one: a return that is there, but that the compiler cannot guarantee is reached. The compiler does a simple flow analysis and is only happy when every possible path ends in a return. It does not treat if (true) as special, so as far as it is concerned there is a path that falls off the end:

The flow analysis never looks at an if condition’s value, not even the literal true: an if with no else is always assumed to be skippable.
This return is correct and has the right type, but it sits inside the if, so it covers only the path where the condition holds.
The path that skips the if arrives here without a value, so the compiler gives the same error as for no return at all (ECJ, at the method’s name: This method must return a result of type boolean; javac, at this brace: missing return statement).
Nothing runs until the method compiles. Drop the pointless if, or give it an else that also returns, as in the next example.

Whereas this quite stupid code satisfies it, because both branches return:

The test depends on n, so the compiler cannot know which way it goes — and does not need to, as long as each branch ends in a return.
When n is below 10, the method ends here and hands back the comparison.
With an else, exactly one of the two blocks always runs, so no path can skip both. Without it the if could be skipped, as in the last example.
Every path now ends in a return, so the method compiles. Both branches return the same thing, which is what makes it “quite stupid”: a single return n % f == 0; would do.

Mistake	This console (ECJ)	Ed (`javac`)
wrong return type	Type mismatch: cannot convert from int to boolean	incompatible types: int cannot be converted to boolean
no reachable `return`	This method must return a result of type boolean	missing return statement

2.4`return` in a `void` method: stopping early

A void method can contain return too — it just cannot take a value. It simply ends the method there. Enter 1, then try 12:

In a method with a return type, return must carry a value of that type. Compare the bare return; in main below.
main is a void method like any other, so it may contain return — but only without a value.
Numbers below 2 have no factors from 2 upwards, so there is nothing to do. printFactors would print nothing for them anyway (its loop test fails at once), but the guard states the rule plainly at the top.
No value after return: it ends the method on the spot, and leaving main ends the program. return 0; here would not compile: Void methods cannot return a value (Ed: incompatible types: unexpected return value).
With input 1 the early return fires, this line is skipped and only the prompt appears. With 12 it runs and lists the factors 2, 3, 4, 6 and 12.

And the Ed lesson’s last example, which is missing an access modifier and ridiculous. It always returns a value, it has the right type, it compiles — and it is still wrong. The compiler checks the shape of a method, never whether it does what its name promises:

xkcd comic: a method getRandomNumber that always returns 4, with the comment 'chosen by fair dice roll, guaranteed to be random' — xkcd 221, *Random Number* (2007) — Randall Munroe, CC BY-NC 2.5

2.5A typical program with return values, explained

Three methods that hand their results back: one returns an int from inside a loop, one returns a comparison directly, and a void one uses a bare return to stop early. Point at an underlined part to see what it does, then press Run.

The int before the name says every call hands back exactly one int. The compiler holds the method to that on every path through it.
The first factor found is the smallest, so it is handed back at once. return ends the whole method, not just the loop — no break needed, and the larger values of f are never tried.
Reached only when the loop finds no factor, so n is its own smallest factor. Delete it and the compiler objects, because the loop might end without returning: This method must return a result of type int (Ed: missing return statement).
The whole expression is a boolean, so it goes straight after return — no if (…) return true; else return false;. The n >= 2 part matters: smallestFactor(1) returns 1, so without it 1 would count as prime.
The call runs smallestFactor and is replaced by the value it returns, saved here so it can be used twice below. Only the value comes back: this f is a new variable, not the loop’s f.
A bare return ends printSplit at once and goes back to the caller, so nothing is printed for a prime or for anything below 2. In a void method it cannot carry a value: return f; here gives Void methods cannot return a value (Ed: incompatible types: unexpected return value).
smallestFactor returns a single value, so the caller works out the other factor: 35 / 5 is exactly 7, because f divides n. The brackets are only for readability — / is done before + anyway.
The returned true takes the call’s place in the expression, and + joins it onto the string: Is 13 prime? true.
It prints nothing: 13 is its own smallest factor, so the early return fires. A void method gives back no value, so it can only be a statement on its own — System.out.println(printSplit(13)) will not compile.

03Parameters, overloading, varargs

3.1The parameter list

The parameter list says what data the method expects — above all, what types — and declares the names used for that data inside the method. It is effectively a comma-separated set of variable declarations. Those variables exist only inside the method (though the data may exist outside as well), and they are removed when the method ends.

Two words worth keeping apart

The variables in the header — a and b in add(int a, int b) — are parameters. The values you hand over at the call — n and m in add(n, m) — are arguments. When the call happens, each parameter is a brand new variable, initialised with the value of its argument. Section 7 is about what “the value” means there.

The number, order and types are strict. The compiler only allows a call if the arguments match in order, number and type; it will not fill in any blanks, and unlike several other languages (Python among them — section 5) Java has no default values for parameters.

3.2Wrong type, wrong number

Both mistakes in one program. Run it and read both errors, starting with the first:

Two variable declarations separated by a comma. Every call must supply exactly two values, in this order, each an int — or a smaller whole-number type such as short, which Java widens to int automatically.
Inside the method, a and b behave like any local variable, already holding the arguments’ values. They are created afresh at each call and removed when add returns.
The compiler checks the whole class before anything runs and reports both errors together. With a compile error there is no program, so main never starts and neither line prints.
The quotes make this a String, and Java never turns a String into an int for you. The argument types are (int, String), which do not match add(int, int).
add declares two parameters, and Java will not drop the extra argument — nor, having no default values, fill in a missing one: add(1) is rejected for the same reason.

Here both are reported as not applicable for the arguments, with the argument types listed so you can compare them with add(int, int). On Ed, javac calls the first one an incompatible types error, and the second a cannot be applied to given types error whose reason line says it plainly: actual and formal argument lists differ in length.

3.3Overloading: one name, several parameter lists

Type, order and number are also how Java decides which method to run — because Java does let you reuse a method name, as long as the parameter lists differ. This is method overloading (or ad-hoc polymorphism).

You have been using it all along. System.out is a PrintStream, and PrintStream has ten versions of println: one with no parameters, and one each for boolean, char, int, long, float, double, char[], String and Object. Every time you printed a different type, you called a different method.

Check it yourself

With a JDK installed, javap java.io.PrintStream lists every method of the class — the ten printlns are all there. Documentation is good; asking the actual library is better.

Building on the factors example: a three-parameter isFactor and a two-parameter printFactors to find common factors. Enter 2, then two numbers:

Overloading: allowed because three ints differ from line 6’s two. Java tells the versions apart only by the number, order and types of the parameters — never by their names or the return type.
% gives the remainder, so each comparison asks “does f divide this exactly?”. && is true only if both are, and skips the right-hand side when the left is already false.
Two int arguments match only the two-parameter isFactor, so the one-number printFactors always uses that version.
A static method of the Math class that returns the smaller of its two arguments. No common factor can be larger than the smaller number, so the loop stops there. Math.min is itself overloaded, for int, long, float and double.
Three ints, so Java picks the three-parameter version, which checks i against both numbers at once.
The Scanner method nextInt reads the next number typed in and returns it as an int. Typing 2 here leads to the two-number branch.
m was declared inside the if block, so it exists only there — which is all this call needs. With 12 and 18, the common factors found are 2, 3 and 6.
The same name as line 44, but one int argument selects the one-parameter printFactors, which lists every factor of n from 2 up.

Nothing at the call site says which version you mean. printFactors(n, m) has two int arguments, and exactly one printFactors takes two ints — so that is the one that runs.

3.4Variable arguments

Since Java 5 a method can also take a variable number of arguments. Overloading handles most sensible cases, but sometimes it is useful to gather a collection of data more ad hoc. The syntax is <type>... <name>, allowed only on the final parameter; it accepts a sequence of values of that one type, of any length — including zero.

Behind the scenes Java collects the values into an array, and the parameter works exactly like one. You just avoid declaring and filling the array yourself:

The three dots mean “any number of ints, including none”. Java gathers them into an int[] named nums. Only the last parameter may be written this way.
Legal: Java keeps method names and variable names apart, and a method call always has brackets after it. The total starts at 0, ready to be added to.
Because nums really is an array, a for-each loop visits each value in the order the caller wrote them; nums.length would work too.
Adds each value to sum. A one-statement loop body may go on the same line without braces.
Java builds the array {1, 2, 3} behind the scenes and passes it as nums, so the method returns 6.
nums is then an array of length 0 (not null), so the loop body never runs and sum returns 0.
Twelve arguments, and no new code was needed. With overloading alone you would have to write a separate sum for every count you wanted to allow.

Because the parameter really is an array, you can also pass an int[] you already have: sum(new int[] {4, 5}) gives 9.

3.5Functions and procedures

Methods fall into two categories. In practice the words get mixed up all the time, but the distinction is worth having in your head:

(Pure) functions have no side effects and no hidden inputs. They change nothing outside themselves, and the same parameter values always give the same result. isFactor is one.
Procedures have side effects — that is usually their purpose — and often have return type void, because their job is to change something. Printing counts: printFactors is a procedure.

Java has no syntax to tell them apart, so it is on you. In general, write functions, and write procedures only when you are sure that is what is needed. The point is clarity of intent: if you do not know what you mean a method to do, you are likely to write a bad one. Here getValue is a function and setValue a procedure:

Declared in the class but outside every method, and without static, so each Example object has its own value. Unlike a local variable, a field starts with a default: 0 for an int.
Return type int, no parameters and no side effects: it only reads value and hands it back. Calling it changes nothing.
Nothing comes back from setValue; it is called for what it changes. That is why it suits void, while getValue needs a return type.
Copies the parameter into the object’s field. The parameter newValue is removed when the method ends, but the change to value stays.
The methods are not static, so they must run for a particular object. new creates one, with value at its default 0, and e refers to it.
The dot runs getValue for the object e, reading that object’s value — still 0, as nothing has set it.
A void call stands alone: there is no result to print or store. Line 17 then gets 42 from the very same getValue call, because the procedure changed the field in between.

Neither method is static: they read and change the value belonging to one particular Example object, which is why main makes one with new first. That is the classes weeks arriving early.

3.6The pizza shop, with methods

The Ed lesson closes by giving the pizza shop from Weeks 2+3 some methods. Here is one way to do it: a function that builds the menu, a procedure that prints it, a boolean function that answers a question, and a method that keeps asking until it gets a sensible answer. Enter 7 then 2:

Declared outside every method, so all of them can see it. static puts it on the class, so the static methods can use it with no object; final means pizzas can never be assigned a different array.
The empty string takes up index 0 so that menu numbers 1 to 3 are also the array indices — no - 1 needed when looking a choice up.
Return type String: it builds the menu text and returns it, printing nothing. Whoever calls it decides what to do with the text.
Once one side of + is a String, the number i is turned into text and joined; "\n" is a newline. += adds each line to the end of menu.
menu() runs first, and the String it returns is what print receives. print, not println, because the text already ends with a newline.
Answers a yes/no question. pizzas.length is 4, so only 1, 2 and 3 count as on the menu; the filler at index 0 is deliberately left out.
Any type can be a parameter. main passes in its own Scanner, so this method reads the same input instead of making a second Scanner on System.in.
! turns the answer round: the loop repeats while the choice is not on the menu. The input 7 fails once, then 2 passes, and only a valid number is returned.
readSelection only ever returns 1 to 3, so this index is always in range; for 2 it is "Too Much Meat".

Read main first

Four lines of main now tell the whole story, in the methods’ own words. The array has moved out of main to become a private static final member — a program constant, visible to every method of the class. Whether all this “simplifies” a program this small is a fair question; the answer changes as the program grows.

3.7A typical methods program, explained

A floor plan in one short program: an overloaded area for square and rectangular rooms, a varargs total that adds up any number of rooms, and a procedure that prints. Point at an underlined part to see what it does, then press Run.

Declares a variable that exists only inside area. Each call makes a brand new side, initialised with the argument’s value, and removes it when the method ends.
This is overloading: allowed because two doubles differ from one. Only the list of parameter types counts, not the names or the return type: a second area(double length), or an int area(double side), fails with method area(double) is already defined in class FloorPlan.
Java collects the arguments into a double[], so rooms works exactly like an array (rooms.length included). The ... is only allowed on the last parameter.
Because rooms is an array, a for-each loop visits each value in the order the caller wrote them. total changes nothing outside itself, so it is a pure function, like area.
No value comes back; the method is called for its side effect, printing. Writing double x = report("Bedroom", 9.0); does not compile, because there is nothing to store.
A String first, then a double. Swap the arguments — report(bedroom, "Bedroom") — and the compiler rejects the call; it never rearranges them for you.
One argument, so Java runs the one-parameter area; line 23’s two arguments pick the other. The int 3 is widened to 3.0 to fit double side, giving 9.0.
Variables and a literal mix freely, as long as each is a double (or widens to one). rooms becomes {9.0, 10.0, 4.5} and the sum is 23.5.
Varargs accepts an empty sequence: rooms is an array of length 0 (not null), the loop runs no times, and total returns 0.0.

04Functions in Python

4.1Functions encapsulate code

Python has the same tool: a section of code with a clean entry point and a clean exit point, reusable from anywhere in the program. In Python these are usually called functions.

One significant difference: everything in Java lives inside a class, but Python allows code that is not (apparently) in a class, and likewise functions that belong to no class. Python does support object-oriented programming, so classes can certainly have functions of their own — and Python can treat functions as first-class values, with some of the same status as variables. Neither matters yet.

4.2`def` and `return`

def <function name>(<parameter list>):
    <function body>

The parameter list may be empty; the body may not. If you want to write a function but do not know what it does yet, the do-nothing keyword pass is a placeholder. Returning a value uses return, much as in Java — but notice what is missing from the header: there is no return type, so nothing in the signature tells you whether the function returns anything, or what.

Starts a function definition: def, the function’s name, the parameters in brackets, then a colon. The indented line below is the body.
Just two names. There is no type for either one and no return type before the name, so the header alone cannot tell you what goes in or whether anything comes out.
return works out a + b, ends the function and gives that value to the caller, much as in Java.
The arguments are given to the parameters in order, so a is 1 and b is 2. The call is replaced by the returned value, 3, and print receives that. The def must already have run, which is why it comes first.

Without type checking, things get a bit odd. Nothing stops you passing strings, and + on strings joins them:

The same header as before. With no types to check, Python accepts any two arguments; whether they work is decided only when line 2 runs.
Python chooses what + means at run time, from the types of the values it meets: adding for numbers, joining for strings and for lists. One line of code, three different jobs.
Both arguments are str, so + joins them and the function returns the string '12', not the number 3. print shows a string without its quotes.
+ on two lists builds a new list holding the elements of both, [1, 2, 3]; neither argument is changed.

And problems only appear at run time, when the line actually executes:

Running a def only creates the function. Nothing is checked about the types a and b will have, so no problem can show up yet.
A list can only be joined to another list, so + raises TypeError: can only concatenate list (not "dict") to list. The traceback names line 5, where the call was made, and then this line, where the error happened.
This line runs and prints before anything goes wrong: the program was never rejected in advance. Java’s compiler would refuse a call like line 5’s, and nothing at all would run.
Curly braces with key : value pairs make a dictionary (Week 2–3, 10.2). Passing it is allowed — there is no type to check — and the mistake surfaces only inside add.
Python works out the argument first, and the call to add raises the error, so this print never runs and the program stops here.

Documentation is the contract

In Java the header is the contract, and the compiler enforces it. In Python, documentation is often the only practical way to know how a function is meant to be used. The flip side: as long as the caller passes data that works with whatever the function does, the code runs — which is occasionally useful.

4.3A function with no `return` returns `None`

Section 3.5’s procedures have return type void in Java. Python has no such keyword. A function that finishes without a return still hands back a value — a special one called None, which means “nothing here”:

A function with no return — Java would call it a void procedure (3.5). Python has no void, and the header looks exactly like that of a function that does return a value.
print writes the text to the console; it hands nothing back to the caller. After this line the function simply reaches its end.
A body may not be empty, so pass fills the gap: a statement that does nothing. todo can be called, but it has no work to do.
The call runs greet, which prints the greeting. It ends without return, so the value stored in result is None. Java would not compile an assignment from a void method.
None means “nothing here”, but it is still a value (of type NoneType), so print shows it as the word None.
Doing nothing and falling off the end is still finishing without return, so this call is also None, and that is what print receives.

In the words of the Python tutorial, even functions without a return statement “do return a value, albeit a rather boring one. This value is called None”. If you ever see an unexpected None printed, look for a function that printed its answer instead of returning it.

4.4Type hints

Python is dynamically typed, so you have no control over variable types — but for readability a function can be decorated with type hints: : <type> after each parameter, and -> <type> after the parameter list for the return type.

They are not enforced in any way. You can still pass in non-int values and get non-int values back:

: int after each name documents that the argument should be an int. Python records the hint but never checks it.
Placed after the parameter list, before the colon: it says the function hands back an int. A note for the reader, not a promise Python keeps.
Two ints go in and + adds them, so the result is the int 3, just as the header describes.
Two strings go in and nothing objects — not the call, not the return. + joins them and the string '12' comes out. A separate checker such as mypy would flag this line; Python itself does not.

It should also be emphasized that Python will remain a dynamically typed language, and the authors have no desire to ever make type hints mandatory, even by convention.

Guido van Rossum, Jukka Lehtosalo & Łukasz Langa, PEP 484 – Type Hints, 2014

That is the proposal that added type hints to the language, saying in advance that they will never become compulsory. Separate tools can check them for you; Python itself will not.

4.5A typical function program, explained

Four small functions for a unit’s results: two that return a value, one that only prints, and an unfinished placeholder — with type hints, and the None that a function without return hands back. Point at an underlined part to see what it does, then press Run.

def, a name, the parameters in brackets and a colon; the indented lines below are the body. There is no return type, no parameter type and no class around it — leave out the colon and you get SyntaxError: expected ':'.
Ends the function and gives the value to whoever called it — line 15 stores it in avg. / always gives a float, so Sam’s 135 / 3 is 45.0, not 45.
Documents that mark should be a number; Python never checks it. grade("90") is let in and fails only when line 8 runs, with TypeError: '>=' not supported between instances of 'str' and 'int'.
Says the function hands back a string. Like every hint it is a note for the reader, not a rule: without it the function runs exactly the same.
A return leaves the function at once, so for Ana’s 89.0 lines 10–12 never run. That is why line 10 can be a plain if rather than elif.
This header looks just like average’s, yet report only prints and returns nothing — the signature cannot tell you which kind you have. In Java it would be a void procedure (3.5).
A body may not be empty, so pass stands in until the real code is written. Delete it and the program does not start at all: IndentationError: expected an indented block after function definition on line 18.
No class and no main: the unindented lines run top to bottom, and the defs above only create the functions. Move this line above line 14 and it stops with a NameError, because report does not exist yet.
report has no return, so the call prints its line and then hands back None, as line 24 shows. Line 25 gets None from certificate in the same way.

05Fancy things with parameters

Where Java is strict about arguments, Python is freer. It allows default arguments, arguments matched to parameters by name, and variable-length argument lists of two kinds.

5.1Default arguments

A parameter can be given a default value, which lets the caller leave that argument out:

The = "Hi!" makes this parameter optional: a call that leaves it out gets "Hi!". A parameter without a default may not follow one that has one, so def msg(msg = "Hi!", name): is SyntaxError: parameter without a default follows parameter with a default.
Inside the body, msg means the parameter — a string — which hides the function of the same name. Its value is whatever the call passed, or else the default.
One argument for two parameters: "Luke" goes to name by position, and msg falls back on its default. In Java this call would need a second, overloaded method with one parameter (3.3).
With a second argument given, "Good Work" replaces the default — for this call only. The default itself never changes, so the next call that leaves msg out gets "Hi!" again.

Compare section 3.1: Java has no default values, which is one reason Java programmers reach for overloading instead.

5.2Keyword arguments

Arguments can also be given by naming the parameter they belong to — and then the order no longer matters:

Neither parameter has a default, so every call must supply both. Because a call may now use these names, renaming a parameter can break its callers — Java matches arguments by position only.
Inside the function, name and msg are ordinary parameters; nothing shows whether the call passed them by position or by name.
msg= sends "Hi!" to the parameter called msg, wherever it sits in the list. The name must exist: text="Hi!" stops with TypeError: msg() got an unexpected keyword argument 'text'.
name comes first in the header but last here; matching by name makes that irrelevant, so this call does exactly what msg("Luke", "Hi!") does.

You have already used one: print("a", end="") passes end by name. print’s end has a default of "\n", which is why print normally finishes the line.

5.3`*`: a variable argument list

Putting * before a parameter name makes a variable argument list, similar to Java’s ... — but without the type restriction, and without having to come last, if you name the arguments after it:

The * gathers every positional argument into one tuple called names — here ('Luke', 'Cat', 'Rohit', 'Matthew'). Like Java’s String... names, but the values need not share a type, and no arguments at all gives an empty tuple.
Any parameter after *names is keyword-only: the positional arguments all go into the tuple, so msg can be reached only by name. That is the price of the * not coming last, as Java’s ... must.
A tuple is a sequence, like a list, so for visits its items in order — the order the call wrote them. len(names) and names[0] work too.
msg here is the keyword-only parameter, the same "Hi" on every pass; only name changes, so the line runs once for each of the four names.
Because it is named, "Hi" goes to msg instead of into the tuple. The four strings before it are positional, so *names takes them all.

Inside the function, names holds every positional argument, in order — it is a tuple, which is why the for loop works. Because *names swallows every positional argument, msg can now only be given by name. Take the msg= away and see:

msg has no default, so every call must supply it, and after *names the only way is by name. A default, msg="Hi", would let line 5 run — but it would greet Hi as a third person.
Arguments are matched to parameters before the body starts, and here that matching fails, so the loop never runs and nothing is printed.
Without msg=, "Hi" is just a third positional argument, so *names takes it too and nothing is left for msg. Python stops here with TypeError: msg() missing 1 required keyword-only argument: 'msg'; the fix is msg("Luke", "Cat", msg="Hi").

5.4`**`: keyword arguments collected into a dict

Finally, ** before a parameter name collects any named arguments that do not match a parameter, and hands them to you as a dict:

The ** gathers every keyword argument that matches no other parameter into a new dict called data. record has no other parameters, so every named argument lands here; a call with none gives an empty dict, {}.
data is a plain dict, so everything from Weeks 2+3 works on it: data["job"] is 'Lecturer', and data.items() walks the pairs, as 5.6 does.
No parameter called name, job or employer exists: the caller makes the names up, and each becomes a key. Only named arguments are collected — record("Luke") gives TypeError: record() takes 0 positional arguments but 1 was given.

The names become the keys, as strings, in the order you wrote them — the same insertion-ordered dict you met in Weeks 2+3.

5.5Function-ing in the pizza shop

The Python pizza shop gets the same treatment as section 3.6. Notice end="" — a keyword argument — stopping print from adding a blank line after a menu that already ends in one. Enter 0 then 3:

The empty string fills index 0, so each pizza’s number on the menu is also its index in the list. That is why the loop on line 5 starts at 1, and why 0 is not on the menu.
menu returns the text and leaves printing to its caller — a function, in 3.5’s sense. Java’s menu() needed no parameter because the array was a class member; here the list comes in as an argument.
len(pizzas) is 4, and range(1, 4) gives 1, 2, 3: the start is included, the end is not. It is Java’s for (int i = 1; i < pizzas.length; i++).
Python’s + will not join an int to a string — i + ". " raises TypeError: unsupported operand type(s) for +: 'int' and 'str' — so str(i) converts it. Java’s + does that conversion for you.
The and expression is already True or False, so it is returned directly, like Java’s isOnMenu with &&. For 0 the left side is False, so and never looks at the right.
input shows the prompt, waits, and returns the typed line as a string, without the newline; int turns it into a number. Typing something like two would stop the program with a ValueError.
not flips the boolean the call returns, so the loop body runs only while the choice is off the menu — once for the 0, and then the 3 ends it. Whatever the function returns is always a real pizza’s number.
end is one of print’s parameters, with the default "\n" (5.1), given here by name (5.2). menu’s text already ends in a newline, so replacing the default with "" avoids a blank line.
read_selection only returns numbers that passed is_on_menu, so choice is 1, 2 or 3 and this index can never be out of range. Here pizzas is the global list, not a parameter.

Each function takes the list as a parameter, also called pizzas. Inside the function that name is a parameter — a local variable that happens to refer to the same list. Section 7 is about exactly that.

5.6A typical messaging program, explained

A small class messenger that uses every idea of this section: a default argument, arguments given by name, a * list of names followed by a parameter that must be named, and ** collecting a record into a dict. Point at an underlined part to see what it does, then press Run.

If a call leaves text out, it is "Hi!" — line 15 relies on this, while line 16 replaces it. A parameter with a default must come after those without one: def message(text="Hi!", name): is a SyntaxError.
The * collects every positional argument into a tuple, in order: on line 19 names is ('Cat', 'Rohit', 'Matthew'). No names at all is fine too — the tuple is then empty.
Because *names swallows every positional argument, text must be named. It has no default, so announce("Cat", "Room changed") takes both strings as names and stops with TypeError: announce() missing 1 required keyword-only argument: 'text'.
names is a tuple, and len works on it just as on a list. Line 19 stores the result, 3, in sent.
The ** collects every named argument that matches no other parameter into a dict. record has no other parameters, so all three land in data.
print’s end has a default of "\n"; passing "" replaces it, so the next print carries on along the same line. The bare print() on line 13 finally ends it.
Each key is an argument’s name as a string, such as 'job', in the order the call wrote them — so the record prints name, job, employer.
Each argument names its parameter, so the order no longer matters. Positional arguments must still come first: message(text="Hi", "Cat") is SyntaxError: positional argument follows keyword argument.
sender also comes after *names, so it too can only be given by name. This call replaces the default "Luke" with "Cat".

06The call stack and the heap

The methods lesson on Ed stops at “there’s a little more to say about how parameters are handled, … however it is helpful to understand a little more about how variables and their data are handled in memory first”. This section and the next are that little more.

6.1Every call gets a frame

When a method is called, the JVM creates a frame for that call: a private block of memory holding the method’s parameters and local variables. Frames live on the thread’s stack. A call pushes a new frame on top; when the method returns, its frame is popped and destroyed, and the caller’s frame is on top again. That is the whole mechanism behind “parameters are removed once the method terminates” in section 3.1.

Run this and read the indentation: every extra level is one more frame on the stack.

Each call to isFactor pushes a fresh frame holding f, n and, a line later, result. The parameters start as copies of the values passed in the call.
The leading spaces are just part of the string. Each method indents by four more than its caller, so the output’s indentation shows how many frames are on the stack: main at none, printFactors at four, isFactor at eight.
The remainder n % f is worked out first, because % binds tighter than ==; the comparison is true exactly when f divides n. The answer goes into result, a local variable in this frame.
The frame of isFactor, with its f, n and result, is destroyed. Only the boolean value travels back to the call on line 13, where printFactors carries on.
A parameter of printFactors, living in its own frame. It has the same name as main’s n on line 22 and receives a copy of its value, 4, but it is a separate variable.
printFactors pauses here, its n and loop variable i intact, while a frame for isFactor goes on top. The boolean it returns becomes the if condition; the loop makes three such calls, each frame pushed and popped in turn.
main is the first method called, so its frame sits at the bottom of the stack for the whole run. When it returns, the program ends.
Pushes a frame for printFactors, passing the value of main’s n. Line 24 runs only once that frame — and every isFactor frame above it — has been popped.

Three frames, three sets of variables. There are two variables called n down there — one in main, one in printFactors — and a third in isFactor. Same name, different variables.

Where this comes from

This is the model in The Java Virtual Machine Specification, §2.5.2 and §2.6: each thread has a JVM stack that stores frames; “a new frame is created each time a method is invoked” and destroyed when that invocation completes, and the JVM “uses local variables to pass parameters on method invocation”. The spec deliberately leaves the machine-level details to each JVM — this picture is the part every JVM agrees on.

6.2A local variable does not outlive its frame

So a variable declared inside a method simply does not exist anywhere else. total below lives in addUp’s frame, and that frame is gone by the time main asks for it — in fact the compiler refuses before anything runs:

addUp is void, so it hands no value to its caller. Whatever it computes is thrown away with its frame — which is the real bug here.
Declared inside addUp, so total lives in addUp’s frame. Its scope ends at the closing brace on line 6; no other method can name it.
+= adds i to total on each pass of the loop, so for n = 10 it would reach 55 — and then vanish when the method returns.
The call pushes a frame, the loop runs, and the frame is popped again. Because addUp returns nothing, this statement has nothing to keep.
The compile error. main declares no total, and the one in addUp is out of scope, so the compiler refuses before anything runs: Ed’s javac says cannot find symbol; this site’s console words it differently.

Ed’s javac calls this cannot find symbol. The fix is not to make total reachable from main; it is to return it — change void to int, add return total;, and print addUp(10). Section 2.1 again: the return value is how information gets out.

6.3The heap: where objects and arrays live

Frames hold parameters and local variables. They do not hold arrays or objects. Arrays and objects — anything made with new — are allocated on the heap, a separate area shared by the whole program; a variable of array or object type holds only a reference to it. The Java Language Specification puts it in one line: “The reference values (often just references) are pointers to these objects”.

That is why a method can build an array and return it. The method’s frame is destroyed, but the array is not in the frame — it is on the heap, and the caller now holds a reference to it:

The return type int[] means squares hands back a reference to an array of ints, not the elements themselves.
result is a local variable in the frame of squares, so it dies when the method returns. It holds only a reference to the array.
new allocates an array of n ints on the heap, every element starting at 0. The heap is not part of any frame, so the array can outlive this call.
Follows the reference in result to the heap array and stores i * i in element i.
The frame of squares is popped, taking n, i and result with it. The array stays on the heap, and the caller receives the reference to it.
sq, in main’s frame, now refers to the very array result referred to. No elements were copied — only the reference.
Visits every element of the array in order, with s holding a copy of each value; print keeps them all on one line.
With no argument, println prints only a line break, ending the line the loop built.

After squares returns: its frame, and its variable result, are gone. The array survives on the heap because main’s sq refers to it.

You have seen this before

Weeks 2+3, section 8.5 — “Two variables, one array” — ran int[] b = a; and showed that a and b then refer to the same array. That was your first encounter with references. With the heap in the picture it stops being surprising: b = a copied the reference, not the array.

xkcd comic: someone asks for a few pointers for a video game and is given three hexadecimal memory addresses — xkcd 138, *Pointers* (2006) — Randall Munroe, CC BY-NC 2.5

A reference really is a kind of address — the Ed Python lesson says exactly that about Python variables. Java simply never shows you the number, and never lets you do arithmetic on it. You can follow a reference; you cannot forge one.

6.4Nobody frees the heap by hand

Frames are cleaned up automatically on return. Heap objects are cleaned up automatically too, by a garbage collector: once nothing refers to an object any more, the JVM may reclaim its memory. In the spec’s words, heap storage “is reclaimed by an automatic storage management system (known as a garbage collector); objects are never explicitly deallocated”. That is why no program on this page ever says “I am done with this array”.

Did you know?

The stack is not unlimited. If a chain of calls needs more stack than the JVM allows, the specification says the JVM “throws a StackOverflowError”. It sounds exotic; you will meet it the first time you write a method that calls itself and never stops. Source: JVM Specification, §2.5.2.

6.5A typical stack-and-heap program, explained

One method builds an array of temperatures and returns it, another finds the highest, and main shares one array between two variables and then replaces it. Frames, local variables that die with their frame, and arrays that live on the heap behind references, all in one program. Point at an underlined part to see what it does, then press Run.

It lives in the frame of readings, not of main. It shares a name with main’s days on line 20, but it is a separate variable that receives a copy of the value 5.
new allocates the array on the heap, not in the frame. The local variable temps holds only a reference to it.
When readings returns, its frame and every variable in it are popped and destroyed. The array is on the heap, so it survives, and the caller receives the reference, not a copy of the array.
A parameter of highest, in a new frame — not the temps of readings, whose frame is already gone. It refers to the same heap array as main’s week, so no elements are copied.
max is destroyed with the frame of highest; only its value, 26, goes back to line 22. Writing max in main would not compile: javac says cannot find symbol.
A new frame for readings goes on top of main’s, which waits. When it returns, main carries on from here and stores the returned reference in week.
This copies the reference, not the array: both names now refer to the one array on the heap. So after week[0] = 30, backup[0] is 30 too — a real backup needs a new array of its own.
A fresh call builds a new three-element array, and week now refers to it. The old five-element array stays alive because backup still refers to it; only once nothing refers to an array may the garbage collector reclaim it.

07By value or by reference?

Two classic ways a language can pass an argument to a parameter:

Name	What the parameter gets	Can the method change the caller’s variable?
Call by value	a copy of the argument’s value, in a new variable	No — it only ever has the copy
Call by reference	the caller’s variable itself, under another name	Yes — assigning to the parameter assigns to the caller’s variable

Java uses exactly one of these. Python uses something that is easiest to understand once you have Java’s straight. Section 6 is what makes both make sense.

7.1Java passes by value. Always.

The Java Language Specification: when a method is invoked, “the values of the actual argument expressions initialize newly created parameter variables”. New variables, in the new frame, holding copies. So this swap cannot work — predict the output first:

a and b are brand-new variables in swap’s frame. On each call they are initialised with copies of the argument values — here 1 and 2.
temp keeps a’s old value so it is not lost when the next line overwrites a. The swap logic is correct; the problem is which variables it works on.
Assigning to a parameter changes swap’s own variable. Nothing connects a back to x, so x cannot be affected.
Inside swap’s frame the exchange really happened, so this prints inside swap: a = 2, b = 1.
Java evaluates x and y to 1 and 2 and copies those values into a and b. swap is void, so no new value comes back either.
swap’s frame has been popped and x and y were never changed, so this prints after swap: x = 1, y = 2.

a and b were swapped perfectly — inside swap’s frame. Then the frame was popped, and x and y in main’s frame were never touched. For comparison, here is a language that does have call by reference. In C++, an & on a parameter makes it another name for the caller’s variable, and the same swap works:

The & after the type makes a and b other names for the caller’s variables, not new variables holding copies. This is true call by reference.
Because a is the caller’s x under another name, this assignment changes x itself — the same line as in Java’s swap, with the opposite effect.
The call is written exactly as in Java. Only the parameter declarations decide whether swap gets copies of x and y or the variables themselves.

Java has no & parameters and no way to write this. If a Java method needs to produce a new value, it returns it.

7.2…and for arrays, the value is a reference

Now pass an array. The rule has not changed — the parameter gets a copy of the argument’s value. But the value of an array variable is a reference (6.3). So the method gets a copy of the reference, which points at the same array on the heap. Change the array through it, and the caller sees the change:

As always, the parameter is a new variable holding a copy — but what is copied is the value of marks, a reference. So values and marks point at the same array on the heap.
Follows the reference and reads the array’s size, 3. length is a field of the array, not a method, so it has no brackets.
Assigning to an element changes the array itself, not the variable values. Since marks refers to the same array, main will see every doubled element.
Only the reference stored in marks is copied into values. The three ints are not copied: there is still just one array.
marks still points at the array doubleAll changed, so this prints 2 4 6. The " " strings make each + join text rather than add numbers.

Two variables, one array. The reference was copied into the new frame; the array was not.

But reassigning the parameter is a different thing entirely. It points the copy somewhere new; the caller’s variable still points where it always did:

Assigning to values itself overwrites replace’s copy of the reference. main’s marks is a separate variable, so it still points at the old array.
new creates a second array on the heap and gives back a reference to it. Outside a declaration the braces need new int[] in front: values = {7, 8, 9}; does not compile.
This follows values, which now leads to the new array, making it {100, 8, 9}. Nothing else refers to that array, so it is lost when replace returns.
values starts out as a copy of the reference in marks, pointing at {1, 2, 3} — exactly as in doubleAll.
Prints 1 2 3: neither line of replace touched the array marks refers to. Under true call by reference, line 4 would have re-pointed marks itself.

Say it precisely

You will read “Java passes objects by reference”. It does not. Java passes references by value. If it were true call by reference, replace above would have changed marks, and section 7.1’s swap would work. Oracle’s own tutorial says it the right way round: reference parameters “are also passed into methods by value”.

7.3So what swap can work in Java?

One that swaps two elements inside an array. The method still gets a copy of a reference — but it only needs to follow that reference, never to reassign it:

a gets a copy of pair’s reference, so it leads to the same two-element array. The method never assigns to a itself, so the copy is all it needs.
Two ints, copied in like any others: the indexes of the elements to exchange. One method can swap any two positions of any int array.
Copies the int at index i into a local so it is not lost when the next line overwrites a[i]. The same three steps as 7.1’s swap — only the targets differ.
The left-hand side is an element of the shared array, so the assignment follows the reference and changes the array main sees. 7.1’s swap assigned to its parameters themselves.
Everything is passed by value, as always: the reference in pair is copied into a, and the numbers 0 and 1 into i and j.
Prints 2 1: the two elements of the one shared array were exchanged, while pair itself still points at the same array.

Look back at section 3.5: swap and doubleAll are procedures. Changing data through a parameter is a side effect, so a method that does it should say so in its name, and should usually be void.

7.4Python: call by object reference

The Ed lesson calls Python’s model call-by-object, and says that in practice it turns out much like Java. Every Python variable is a reference — its value is where some data is, not the data itself — and calling a function assigns each argument’s reference to a new local name. What you observe then depends on the data.

Immutable data — integers, floats, strings, tuples — cannot be changed in place, so it behaves like pass-by-value: num += 3 makes a new number and points the local num at it.

Calling add3 binds the local name num to the same int object that n refers to — as if num = n ran at the start of the call.
An int cannot be changed in place, so here += means num = num + 3: it creates a new int, 3, and re-points num at it. The 0 that n refers to is untouched.
add3 has no return statement, so it returns None, and the call stands alone as a statement. No assignment to n happens anywhere.
n was never rebound, so this prints 0. To get a new value out, return it: return num + 3 in the function and n = add3(n) in the caller — the same fix as in Java.

Mutable data, such as a list, works like the Java array: the function can change the object that both names refer to.

When append3 is called, l is bound to the very list letters refers to. Only the reference is assigned; the list is not copied.
append adds its argument to the end of the list in place and returns None. It changes the object l refers to, not the name l, so letters sees it too.
append3 returns None; its whole effect is the change to the list, which is why the call stands alone as a statement.
letters still refers to the same list, which now holds four items: ['a', 'b', 'c', 3]. A list may mix types, such as strings and an int.

But assigning to the parameter only re-points the local name — letters and l are two separate variables, and the caller’s still refers to the original list:

At the start of the call, l refers to the same list as letters, exactly as in append3.
Assignment re-points the local l at the int 17 — Python lets a name switch to any type. The list is untouched, and letters, a separate variable, still refers to it.
Prints ['a', 'b', 'c'] unchanged. This is 7.2’s replace again: re-pointing the parameter never reaches the caller’s variable.

Actually, call by object reference would be a better description, since if a mutable object is passed, the caller will see any changes the callee makes to it (items inserted into a list).

The Python Tutorial, §4.8 Defining Functions, footnote 1

The tutorial’s main text says arguments are passed “using call by value (where the value is always an object reference, not the value of the object)”, and the Python FAQ says “arguments are passed by assignment”. Three phrasings, one behaviour — and it is the same behaviour as Java’s arrays in 7.2. You will also see it called call by sharing.

7.5Mutate, or rebind? The one question to ask

In both languages, the question is never “what type is the argument?” but what does the function do to its parameter?

Mutate the object it refers to — values[i] = …, l.append(…) — and the caller sees it.
Rebind the parameter itself — values = …, l = … — and the caller never finds out.

Both in one function. Predict the list before you run it:

items still refers to the list numbers refers to, so append adds 4 to that one shared list.
The list display [0] builds a new one-item list and the local name items is pointed at it. numbers is unaffected, and from here on the function cannot reach the caller’s list.
5 goes into the new list, making it [0, 5]. Nothing outside the function refers to that list, so it is lost when change returns.
Only what happens before the rebind reaches the caller. Swap lines 2 and 3 and numbers would not change at all.
Prints [1, 2, 3, 4]: the shared list gained the 4 at line 2, while the 5 went into the new list made at line 3.

One Python trap

For a list, items += [4] mutates the list in place — unlike num += 3 on an int, which makes a new number. Same operator, different effect, because one type is mutable and the other is not. If a function should not change its caller’s list, do not use += on it.

Inside the method / function	Java	Python	Caller sees it?
assign to a number parameter	a = b;	num += 3	No
change an element / the object	values[i] = 0;	l.append(3)	Yes
assign a new array / list to the parameter	values = new int[3];	l = [0]	No
“change” a string parameter	s = s + "!";	s = s + "!"	No — strings are immutable in both

7.6A typical parameter-passing program, explained

A mark-moderation program that does all three things a method can do with its parameters: assign to an int parameter, change an array through a parameter, and point an array parameter at a new array — and only one of them reaches the caller. Point at an underlined part to see what it does, then press Run.

A parameter is just a local variable of this call, so it can be assigned like any other. Only capped’s own copy becomes 100 — the swap of 7.1 again.
No method can change the caller’s int variable, so the new value goes back this way. A common mistake is writing capped(raw); as a statement on its own: the result is thrown away and nothing has changed.
The value of an array variable is a reference (6.3), so this parameter gets a copy of main’s reference: two variables, both called marks, pointing at one array on the heap.
Assigning to an element follows the reference and changes the shared array itself. That side effect is the method’s whole job, which is why it is void and its name says what it changes (7.3).
Java works out marks[i] + bonus first — 102 for the middle mark — and copies that number into mark. capped gets an int, not the array, so it could not change the array even if it tried.
This points clear’s copy of the reference at a brand-new array of zeros; main’s marks still refers to the old one, so nothing is cleared. To really clear it, mutate instead: marks[i] = 0 in a loop.
63 100 69: the bonus stuck because addBonus changed the array itself, while clear only re-pointed its own parameter.
The value of raw is copied into mark, and the 100 comes back through return into shown. Line 28 prints 104 is shown as 100: raw itself was never touched.

08Records: plain old data

Why this section has no Run buttons

Records arrived in Java 16. The console on this site compiles for Java 8 (see the Playground notes), so it cannot run them. Every example below was compiled and run on a current JDK, and the output shown is the real output. To run them yourself, paste them into Ed, which runs Java 23.

8.1Is there anything Java makes easy?

Python has convenient built-in structures for simple, common cases: list, dict, tuple, set. Java, being Java, never makes anything quite that simple. Which leaves the problem that ended Weeks 2+3 (section 11 there): you want a small structure holding a few values of different types, without any of the fancy parts a full class needs. In short, plain old data.

Weeks 2+3 answered it twice, both unsatisfactorily: parallel arrays kept in step by hand, and a class with public fields and no methods — “deliberately bad OO”. Records are the answer Java itself now gives. They are meant to be something like a C struct: a set of variables bundled so they move around as one unit, without the syntactic bulk of writing a class.

8.2Record syntax

A record is actually a special kind of class with a standardised format — so when you meet classes properly, you can match their parts to what a record does for you. A basic record is:

<access modifier> record <Name>(<type> <name>[, <type> <name>]*) {}

In English: an access modifier (usually public), the keyword record, a name, then a list of variable declarations just like a method’s parameter list — same rules, except that varargs are not allowed. The {} at the end is, for now, just a concession to the implementation; later there is more you can put there. A point in 2D, and a student:

An access modifier, the keyword record, then the name of the new type, capitalised like a class name. Because it is public, it must be saved in its own file, Point.java.
Written exactly like a method’s parameter list: a type and a name for each value, separated by commas. Every Point carries its own x and y, which cannot be changed once set.
Needed even when there is nothing in it — for now just a concession to how records are implemented. Extra methods can go between the braces once classes have been covered.
A String and two ints bundled together — values of different types that Weeks 2+3 had to keep in parallel arrays. Being public too, Student needs a file of its own, Student.java; the two lines are shown together only to compare them.

Like a public class, a public record must be in its own file with the same name — Point.java. A non-public one can be declared inside another class, which is what the examples below do so each fits in one file.

8.3What the one line gives you

You get	For `record Point(double x, double y)`
a variable for each component	`x` and `y`, which cannot be changed once set
a method for each component, with the same name, returning its value	p.x() p.y()
a constructor — a special method for building one, arguments in declaration order	new Point(1.5, -3.2)
a readable form for printing	Point[x=1.5, y=-3.2]

What you do not get is any way to change the values. That can be added, but it is not the default — so a simple record is very close to a Python tuple in how you use it: build it once, read it as often as you like.

Did you know?

The JEP that finalised records describes them as classes that act as “transparent carriers for immutable data” and adds: “Records can be thought of as nominal tuples” — tuples whose type has a name. They took three releases to arrive: a preview in JDK 14, a second preview in JDK 15, and final in JDK 16, released on 16 March 2021. Source: JEP 395 — Records and JDK 16.

8.4Making one, and reading it

Create an instance with new and the values, in the order the components were declared — exactly like calling a method:

No public, and declared inside ExampleOfARecordInUse, so it can share this file. From here on Point is a type the whole class can use, just like String.
The record’s name is used as a type. As with arrays in sections 6 and 7, p holds a reference to the record, which itself lives on the heap.
new and the record’s name call the constructor the record wrote for you. The arguments go in declaration order, like a method call: 1.5 becomes x and -3.2 becomes y.
Given a whole record, println uses the readable form the record wrote: the type’s name, then each component as name=value in square brackets, Point[x=1.5, y=-3.2].

Output

Point[x=1.5, y=-3.2]

To use the values, call the method with the component’s name. For a record with a component x, p.x() returns the value of x for the record p:

This is what the record generates for the component x: a method with the same name, no parameters, returning the value. It is only a comment here because Java writes it for you.
Each new builds a separate record with its own x and y, so p and q refer to two different objects.
Calls p’s x method, which returns the double 1.5. The brackets are part of it: it is a method call, as the comment on line 4 shows.
The same method called on q returns its x, 5.6. Both calls give doubles, so dx is ordinary arithmetic: 1.5 − 5.6 is −4.1.
A static method of the built-in Math class: it takes a double and returns its square root as a double. Squaring dx and dy and adding them is Pythagoras.
Joining a record to a string with + uses the same readable form as printing it, so p appears as Point[x=1.5, y=-3.2] in the middle of the sentence.

Output

The distance between Point[x=1.5, y=-3.2] and Point[x=5.6, y=8.7] is 12.586500705120544

And trying to change a component is a compile error — the variables are final, Java’s word for “cannot be reassigned”:

The constructor is the only place the components get their values. To “move” the point, build a new one instead: p = new Point(10, p.y());.
Each component is a final variable, so javac rejects this line: cannot assign a value to final variable x. (That is its wording when Point is declared inside the same class, as in 8.4; with Point in its own file it says x has private access in Point.)

javac says

error: cannot assign a value to final variable x

8.5Weeks 2+3’s program, with a record

Here is the Favourites program from Weeks 2+3, section 11.5 — the one with the “deliberately bad” public-field class — rewritten with a record. One array, both fields, and no way to put a name with the wrong number:

A String and an int in one type, replacing Weeks 2+3’s class with public fields. Neither component can be reassigned once set, so no other code can overwrite them.
nextInt reads the number but leaves the Enter key’s newline waiting. This nextLine call reads and discards it, so the nextLine on line 17 gets the name rather than an empty string.
Room for n references to Person, each starting as null: no Person exists until the loop builds one. Weeks 2+3 needed two parallel arrays for this.
The constructor takes both values at once, in declaration order, so there is never a Person with a name but no number. Swap them, new Person(num, name), and javac says incompatible types: int cannot be converted to String.
people[i] picks one Person out of the array, then .name() calls its generated method, which returns the String stored in it.
Returns the int component. Joined to a string with + it becomes text, like any int, giving (Bach, 7).
Passes the record itself, not its parts, so println uses its readable form: Person[name=Bach, num=7]. If n were 0, people[0] would throw ArrayIndexOutOfBoundsException.

Terminal, with the input 2, Bach, 7, Linh, 3

How many people? 2
Enter a name: Bach
Enter their favourite number: 7
Enter a name: Linh
Enter their favourite number: 3
All the people and their favourite numbers: (Bach, 7) (Linh, 3)
Person[name=Bach, num=7]

Compare it with the class in Weeks 2+3: no public fields that any code could overwrite, no half-built object with a name but no number yet, and printing works without writing anything.

Records also answer section 2.1’s puzzle — a method can only return one value. If a method genuinely needs to produce two, a record puts them together as one:

Both components are ints: the point here is not mixing types but bundling two answers, so that a method can hand them back together.
The method promises to return a Range — still one value, as section 2.1 requires, but one that holds two numbers.
Java is case-sensitive, so the method range and the record type Range are different names. Naming a method after what it returns is common.
Both min and max begin as the first mark, so every comparison in the loop has a real value to beat. An empty array would throw ArrayIndexOutOfBoundsException here.
v takes each element in turn, and the two ifs keep the smallest and largest seen so far. No index is needed.
Builds a Range from the two local variables, min first as declared, and returns a reference to it. The locals only share their names with the components; they are separate variables.
The call hands back a single Range, so one variable holds both results — no parallel arrays or extra methods needed.
r.min() and r.max() are the methods the record wrote; they return the two ints, 55 and 91, which + joins into the sentence.
The printed form, Range[min=55, max=91], uses the component names from line 3, so a well-named record explains its own output.

Output

Lowest 55, highest 91
Range[min=55, max=91]

8.6What else can they do?

Records are implemented as specialised classes, so a lot more can be added: extra methods, private members, interfaces, generics — almost everything an ordinary class can do. All of that needs classes first, which is where the subject goes next. For now, a record is the right tool whenever you would otherwise reach for parallel arrays or a tuple.

And a record is an object

So everything in sections 6 and 7 applies: new Point(…) is allocated on the heap, a Point variable holds a reference, and passing a Point to a method copies the reference. Because a record’s components cannot be reassigned, though, a method that receives one cannot change them behind the caller’s back — one less side effect to worry about.

8.7A typical record program, explained

A small marks program that keeps each student’s name and mark together in a record: one array of records instead of parallel arrays, a method that returns a whole student, and a “change” that really builds a new record. Point at an underlined part to see what it does; the output under the code comes from a current JDK.

The keyword record and a name give you a type with a constructor, a method per component and a readable printed form. Declared inside Marks, it keeps the program in one file; written on its own as public record Student, it would need its own file, Student.java.
Written just like a method’s parameter list. Each component becomes a variable that cannot be changed, a method with the same name, and one argument of the constructor, in this order.
Each element is a whole student, name and mark together, so they can never get out of step. Weeks 2+3 needed two parallel arrays for this.
The record wrote a method called mark that returns this student’s mark. It is a method call, so the brackets are part of it, as with p.x() in 8.4.
A method can return only one value, but one Student carries a name and a mark. What comes back is a reference to the record already in the array — no new Student is made.
Components are final, so s.mark += bonus does not compile: error: cannot assign a value to final variable mark. Instead, make a new Student from the old one’s parts, with the mark raised.
The values go in the order the components were declared: name, then mark. Swap them, new Student(72, "Linh"), and javac says incompatible types: int cannot be converted to String.
The array slot now refers to the new record, with 65. The old one is untouched — nothing can change it — and before still refers to it.
Joining a record to a string uses the readable form the record wrote for you: the type’s name, then name=value for each component in square brackets.

Best: An, 91
Student[name=Bach, mark=55] became Student[name=Bach, mark=65]

09Coding exercises

Eight exercises, marked automatically against test cases — the same idea as the Ed labs, but nothing here is recorded or submitted. Write your answer, press Run tests, and read what comes back. A worked solution sits under each one, but try it first.

Output must match exactly

A capital letter or a missing full stop fails the test, exactly as it would on Ed. Trailing spaces and the final newline are the only things forgiven.

The tests check output, not structure

A program that prints the right thing from one long main will pass — and miss the point. Each brief names the method or function to write; write it, and call it.

10Team activity

Three or four people, fifteen minutes, then two minutes to report back. These run in the lecture and in the lab — class activities like these count towards the participation side of your mark.

Activity 1 · 10 min · no computers

Find the verbs

Take the parallel-arrays Favourites program from Weeks 2+3 (section 11.3 there), which is one long main.

Mark every block of lines that does one well-defined job. Give each a method name — a verb, or a question for a boolean.
Write each method’s header: static, return type, parameter list.
Which of them are functions and which are procedures (section 3.5)?

Report back: the method your group argued longest about naming, and the name you settled on.

Activity 2 · 10 min · paper, then one laptop

Draw the stack

Section 6.1’s CallStack program calls printFactors(4). On paper, draw the stack of frames at the moment each line is printed — frame names and the value of every variable in each frame.

What is the largest number of frames on the stack at once?
How many separate frames for isFactor are created over the whole run?
Then run it. Does the indentation agree with your drawing?

Report back: your answer to question 2, and how you counted it.

Activity 3 · 10 min · one laptop per group

Mutate or rebind? Fool your neighbours

Each person writes a short function, in Java or Python, that takes an array or list and does something to its parameter — then calls it and prints the caller’s data. The rest of the group predicts the output before it is run.

Which predictions were wrong, and was the mistake about mutating or rebinding?
Did anyone use += on a Python list? What happened?

Report back: the snippet that fooled the most people.

Why we do this out loud

The first code comprehension check is this week: you explain code, in person. Tracing a stack and saying “this line changes the caller’s array, that one does not” is exactly the kind of explanation it asks for.

M1Java and Python, side by side

Reference, not reading. Everything this week has an equivalent in the other language — or pointedly does not.

Defining and calling

Idea	Java	Python
define	static int add(int a, int b) { … }	def add(a, b):
must live in a class?	yes	no
parameter types	required, checked by the compiler	optional hints, never checked: `a: int`
return type	required; `void` for none	optional hint: `-> int`
return nothing	`void` method; bare `return;` ends it early	no `return`, or bare `return`: the call gives `None`
empty body placeholder	{ }	pass
wrong number of arguments	compile error	`TypeError` when the call runs

Parameters

Idea	Java	Python
default values	not allowed — overload instead	def msg(name, msg="Hi!"):
arguments by name	not allowed	msg(msg="Hi!", name="Luke")
same name, different parameters	overloading	not available — a second `def` replaces the first
any number of arguments	`int... nums` — last only, one type, arrives as an array	`*names` — any types, arrives as a tuple
any named arguments	not available	`**data` — arrives as a dict
how arguments are passed	by value; for arrays and objects the value is a reference	by object reference (“by assignment”)
bundle a few values	record Point(double x, double y) {}	(1.5, -3.2)

03 · This week

What to actually do

On Ed, work through the three Week 4 lessons. This order matches the sections above:

Basics of Methods in Java — sections 1 to 3
Functions in Python — sections 4, 5 and 7.4
Plain Old Data in Java — Record Classes — section 8

Sections 6 and 7 go further than Ed

The Java methods lesson ends by promising more on how parameters relate to values outside the method, once you know how memory is handled. Sections 6 and 7 are that material, for both languages. It is not decoration: it explains every “why did my array change?” question you will have for the rest of the subject.

Code comprehension 1 · 5%

The first code comprehension stage is scheduled for this week, timetabling permitting. You will be asked to explain code, in person. Canvas → Assignments is authoritative for what is due and when; where this page differs, Canvas and the announcements win. Assessed lab exercises are still due 11:55pm the Monday of the following week, and you must pass all test cases in an exercise to get its marks.

If you only do one thing

For every runnable block in section 7, predict the output before you press Run, and say out loud which line mutates and which line rebinds. That habit is most of this week.

Coming up in Week 5: classes, objects and enums — the methods from this week finally get objects to belong to.

Sources

Everything cited on this page

The lecture content comes from the Week 4 lessons on Ed. Sections 6 and 7 extend them; the links below are for those sections and for the claims this page adds around the lessons — checking a source yourself is a better habit than trusting any lecture slide, including ours.

Specifications and documentation

Used in	Source
1–3	Oracle — Defining Methods, The Java Tutorials
3.3	`javap java.io.PrintStream` on JDK 26 — ten `println` overloads
6.1, 6.3, 6.4	The Java Virtual Machine Specification, Java SE 25, §2.5.2 (JVM stacks, `StackOverflowError`), §2.5.3 (heap, garbage collector), §2.6 and §2.6.1 (frames, local variables used to pass parameters)
6.3	The Java Language Specification, Java SE 25, §4.3.1 — “The reference values (often just references) are pointers to these objects”
7.1	The Java Language Specification, Java SE 25, §8.4.1 — “the values of the actual argument expressions initialize newly created parameter variables”
7.2	Oracle — Passing Information to a Method or a Constructor — reference parameters “are also passed into methods by value”
4.3, 7.4	The Python Tutorial, §4.8 Defining Functions — the `None` passage, “call by value (where the value is always an object reference …)”, and footnote 1
7.4	Python Programming FAQ — How do I write a function with output parameters (call by reference)?
8	Oracle — Record Classes, Java SE 21 language guide; JEP 395 — Records; JDK 16 (General Availability 16 March 2021)

Quotations

Every quotation on this page was checked against a primary source — the original book, proposal or documentation, not a quotation website.

Used in	Source
1.1	Brian W. Kernighan & P. J. Plauger, The Elements of Programming Style, 2nd ed., McGraw-Hill, 1978 — “Modularize. Use subroutines.” (ch. 4)
4.4	Guido van Rossum, Jukka Lehtosalo & Łukasz Langa, PEP 484 – Type Hints, created 29 September 2014, section “Non-goals”
7.4	The Python Tutorial, §4.8 Defining Functions, footnote 1
8.3	JEP 395 — Records, Summary — “transparent carriers for immutable data”, “nominal tuples”

Comics

All by Randall Munroe, xkcd.com, used under CC BY-NC 2.5: 138 (Pointers, 2006) and 221 (Random Number, 2007 — the one the Ed methods lesson uses).

Photographs

From Wikimedia Commons, reused under the licence each one names. Author and licence come from the Commons API rather than from anyone’s memory — see media/fetch-photo.py.

Image	Source
edsac	EDSAC (10) — Computer Laboratory, University of Cambridge, reproduced by permission · CC BY 2.0
stack-plates	Stack of dinner plates — Santeri Viinamäki, 2016 · CC BY-SA 4.0
kernighan	Brian Kernighan in 2012 at Bell Labs 1(cropped) — Ben Lowe, 2012 · CC BY 2.0

Articles

Used in	Source
1.1	Function (computer programming) — History: Wilkes, Wheeler and Gill and the closed subroutine; Turing’s 1945 ACE proposal
1.1	David Wheeler (computer scientist) — EDSAC, the closed subroutine around 1951, the “Wheeler jump”

Methods, Functions and Records

The lecture, then the practice

01What methods are for

1.1Pieces of code with well-defined inputs

1.2The method header, in five parts

1.3main, read the same way

1.4Without static

1.5A typical first program with methods, explained

02Return values and return

2.1Getting information out

2.2The return statement

2.3Three ways to get it wrong

2.4return in a void method: stopping early

2.5A typical program with return values, explained

03Parameters, overloading, varargs

3.1The parameter list

3.2Wrong type, wrong number

3.3Overloading: one name, several parameter lists

3.4Variable arguments

3.5Functions and procedures

3.6The pizza shop, with methods

3.7A typical methods program, explained

04Functions in Python

4.1Functions encapsulate code

4.2def and return

4.3A function with no return returns None

4.4Type hints

4.5A typical function program, explained

05Fancy things with parameters

5.1Default arguments

5.2Keyword arguments

5.3*: a variable argument list

5.4**: keyword arguments collected into a dict

5.5Function-ing in the pizza shop

5.6A typical messaging program, explained

06The call stack and the heap

6.1Every call gets a frame

6.2A local variable does not outlive its frame

6.3The heap: where objects and arrays live

6.4Nobody frees the heap by hand

6.5A typical stack-and-heap program, explained

07By value or by reference?

7.1Java passes by value. Always.

7.2…and for arrays, the value is a reference

7.3So what swap can work in Java?

7.4Python: call by object reference

7.5Mutate, or rebind? The one question to ask

7.6A typical parameter-passing program, explained

08Records: plain old data

8.1Is there anything Java makes easy?

8.2Record syntax

8.3What the one line gives you

8.4Making one, and reading it

8.5Weeks 2+3’s program, with a record

8.6What else can they do?

8.7A typical record program, explained

09Coding exercises

10Team activity

Find the verbs

Draw the stack

Mutate or rebind? Fool your neighbours

11Quiz

12Further reading

The official word

Defining methods

Passing information to a method

Defining functions, in Python

Record classes

Behind the claims on this page

JVM Specification, §2.5–2.6

Java Language Specification, §8.4.1

Python FAQ: call by reference?

PEP 484 — Type Hints

JEP 395 — Records

M1Java and Python, side by side

Defining and calling

Parameters

What to actually do

Everything cited on this page

Specifications and documentation

1.3`main`, read the same way

1.4Without `static`

02Return values and `return`

2.2The `return` statement

2.4`return` in a `void` method: stopping early

4.2`def` and `return`

4.3A function with no `return` returns `None`

5.3`*`: a variable argument list

5.4`**`: keyword arguments collected into a dict