Method Signatures

Suppose the morning announcements remind students to bring their library books, and the reminder has to appear in several places in a program. You could type the same System.out.println statement three times. But if the wording ever changes, you would have to find and fix every copy, and missing one would leave the program inconsistent. It would be better to write the reminder once, give it a name, and then say “do the reminder now” wherever it is needed.

That is exactly what a method does. First, a word about braces. Since Topic 1.1 you have seen { and } grouping lines together. Any section of code enclosed in a pair of braces is called a block of code. The body of main is a block, and so is the whole class.

A method is a block of code with a name, and the code inside it runs only when the method is called. To call a method means to tell Java “run that method’s code now.” You write a call as the method’s name followed by parentheses, ending with a semicolon: printReminder();.

You have been calling methods since your first program. System.out.println("Hi"); is a call to a method named println that someone else wrote. And main is a method too: it is the one Java calls for you automatically when the program starts.

public class NeverCalled
{
    public static void main(String[] args)
    {
        System.out.println("Homeroom starts at 8:00.");
        System.out.println("Have a good day!");
    }

    public static void printReminder()
    {
        System.out.println("Bring your library book.");
    }
}

Homeroom starts at 8:00.
Have a good day!

Now change one thing: add two calls to printReminder inside main.

public class ReminderTwice
{
    public static void main(String[] args)
    {
        System.out.println("Homeroom starts at 8:00.");
        printReminder();
        System.out.println("Lunch is at 11:30.");
        printReminder();
    }

    public static void printReminder()
    {
        System.out.println("Bring your library book.");
    }
}

Homeroom starts at 8:00.
Bring your library book.
Lunch is at 11:30.
Bring your library book.

Each call on lines 6 and 8 runs the method’s block once, so the reminder appears twice even though its println statement is written only once. If the reminder’s wording changes, you edit line 13 and both calls pick up the change. Because printReminder is in the same class as main, the call is just its name and parentheses; Topic 1.10 explains the full rules for calling methods.

public class MissingParens
{
    public static void main(String[] args)
    {
        System.out.println("Homeroom starts at 8:00.");
        printReminder;
    }

    public static void printReminder()
    {
        System.out.println("Bring your library book.");
    }
}

public class Practice
{
    public static void main(String[] args)
    {
        printWarmUp();
        System.out.println("Run three laps.");
        printWarmUp();
    }

    public static void printWarmUp()
    {
        System.out.println("Stretch for five minutes.");
    }

    public static void printCoolDown()
    {
        System.out.println("Walk one lap slowly.");
    }
}

Stretch for five minutes.
Run three laps.
Stretch for five minutes.

How does System.out.println actually get letters onto your screen? You have no idea, and you have used it in every program since Topic 1.1. That is not a gap in your knowledge; it is the whole point. You only need to know what it does (display a value and move to a new line), not how it does it.

In plain words: a method lets the person who uses it ignore the details of how it works. A driver uses a steering wheel without knowing how the steering system is built; turning the wheel left turns the car left, and that is all the driver needs. The name for this idea is procedural abstraction: using a method by knowing what it does, even if you do not know how it was written. (“Abstraction” means hiding details so you can think about the bigger picture.)

So where do you learn what a method does? From its documentation. In Topic 1.7 you saw that an API’s documentation describes the behaviors a class offers, and in Topic 1.8 you saw documentation comments that state preconditions and postconditions. That documentation is your whole view of the method. Here is a simplified version of the documentation for the Math class’s square-root method:

/**
 * Returns the positive square root of a.
 * Precondition: a is not negative.
 */
public static double sqrt(double a)

The comment tells you what goes in (a number that is not negative), and what comes out (its square root). The code that computes square roots is nowhere in sight, and you do not need it.

System.out.println(Math.sqrt(144.0));
System.out.println(Math.sqrt(2.0));

12.0
1.4142135623730951

Now change the situation: use the same method for a new problem. A ladder leans against a wall, its top 3 meters up the wall, its base 4 meters from the wall. From geometry, the ladder’s length is the square root of (3 × 3 + 4 × 4).

double wallHeight = 3.0;
double distanceFromWall = 4.0;
double ladderLength = Math.sqrt(wallHeight * wallHeight + distanceFromWall * distanceFromWall);
System.out.println(ladderLength);

5.0

Java first evaluates the expression inside the parentheses, 9.0 + 16.0 = 25.0, and then sqrt gives back 5.0. The method was written long before anyone thought about your ladder, but because you know what it does, you can use it anywhere you need a square root. That reuse is the payoff of procedural abstraction: one well-documented method serves many programs, and nobody has to write square-root code twice.

System.out.println(Math.pow(2, 3));

In Topic 1.1 you learned that statements run one at a time, top to bottom. But a method’s statements are not where the call is; they are somewhere else in the file. So when Java reaches a call, what happens to “top to bottom”? And once the method finishes, where does the program pick up again?

In plain words: a method call is like a detour. You are reading a recipe, and step 3 says “make the sauce (see page 40).” You flip to page 40, do every step there, and then come back to step 4 of the original recipe, the step right after the one that sent you away. You do not start the recipe over, and you do not skip ahead.

The order in which statements actually run is called the flow of control. A method call interrupts the normal top-to-bottom order: Java pauses where it is, runs the statements in the method, and when the method’s last statement has run, control returns to the point immediately after the call. (A method can also hand back control early with a return statement; you will see that in 1.9.7.)

public class Announcements
{
    public static void main(String[] args)
    {
        System.out.println("Good morning, Hoppers!");
        printLunchMenu();
        System.out.println("Have a great day!");
    }

    public static void printLunchMenu()
    {
        System.out.println("Lunch: tacos");
        System.out.println("Side: apple slices");
    }
}

Good morning, Hoppers!
Lunch: tacos
Side: apple slices
Have a great day!

Now change one thing: let a method call another method. Here main calls printSchedule, and printSchedule itself calls printLunchMenu.

public class NestedCalls
{
    public static void main(String[] args)
    {
        System.out.println("Start of announcements");
        printSchedule();
        System.out.println("End of announcements");
    }

    public static void printSchedule()
    {
        System.out.println("Period 1: Math");
        printLunchMenu();
        System.out.println("Period 5: Art");
    }

    public static void printLunchMenu()
    {
        System.out.println("Lunch: tacos");
    }
}

Start of announcements
Period 1: Math
Lunch: tacos
Period 5: Art
End of announcements

The same rule applies at every level. Line 6 sends control into printSchedule, which prints line 12. Line 13 sends control into printLunchMenu, which prints line 19. When printLunchMenu finishes, control returns to the point right after its call, which is line 14 inside printSchedule, not main. Only when printSchedule finishes does control return to main at line 7. Each method returns to whoever called it.

public class DefinedFirst
{
    public static void printBell()
    {
        System.out.println("The bell rings.");
    }

    public static void main(String[] args)
    {
        System.out.println("First period");
        printBell();
        System.out.println("Second period");
    }
}

First period
The bell rings.
Second period

public class FieldTrip
{
    public static void main(String[] args)
    {
        System.out.println("Board the bus.");
        visitMuseum();
        eatLunch();
        System.out.println("Ride home.");
    }

    public static void visitMuseum()
    {
        System.out.println("See the dinosaurs.");
        eatLunch();
        System.out.println("Visit the gift shop.");
    }

    public static void eatLunch()
    {
        System.out.println("Eat lunch.");
    }
}

Board the bus.
See the dinosaurs.
Eat lunch.
Visit the gift shop.
Eat lunch.
Ride home.

printReminder prints the same thing every time. That is fine for a reminder, but most useful methods need to work with different values each time. Math.sqrt would be pointless if it could only find the square root of one number. A ticket booth needs to print the total for any price and any number of tickets. How does a method get the values it should work on?

In plain words: the method announces, in its first line, the values it needs and gives each one a name and a type. Whoever calls the method supplies actual values for those names. Think of a form with blanks labeled “Price” and “Number of tickets”: the form (the method) defines the blanks, and each customer (each call) fills them in.

Reading a method header

The first line of a method is its method header. Here is the header of a method that prints the cost of some movie tickets:

public static void printTotal(double ticketPrice, int tickets)

A parameter is a variable declared in the header of a method. It can be used inside the method’s body, and it is how values get into the method. (Java has one other kind of header with parameters, belonging to a constructor; you will meet constructors in Topic 1.13.)

An argument is a value passed into a method when the method is called. In the call printTotal(12.5, 3), the arguments are 12.5 and 3. When the call happens, each parameter starts out holding the value of the matching argument: the first parameter gets the first argument, the second gets the second, and so on.

public class TicketTotal
{
    public static void main(String[] args)
    {
        printTotal(12.5, 3);
        printTotal(8.0, 2);
    }

    public static void printTotal(double ticketPrice, int tickets)
    {
        System.out.println(ticketPrice * tickets);
    }
}

Now change what the arguments look like. An argument does not have to be a literal number. It can be a variable or a whole expression, and its name has nothing to do with the parameter’s name.

public class TicketVariables
{
    public static void main(String[] args)
    {
        double matinee = 9.5;
        int groupSize = 4;
        printTotal(matinee, groupSize);
        printTotal(matinee, groupSize + 1);
    }

    public static void printTotal(double ticketPrice, int tickets)
    {
        System.out.println(ticketPrice * tickets);
    }
}

38.0
47.5

On line 7, Java looks up the values of matinee (9.5) and groupSize (4) and passes those values; inside the method they are known as ticketPrice and tickets. On line 8, Java first evaluates groupSize + 1 to get 5, and passes 5. So 9.5 × 4 = 38.0 and 9.5 × 5 = 47.5. What gets passed is always a value; matching is done by position, never by name.

public class ParameterOutside
{
    public static void main(String[] args)
    {
        printTotal(12.5, 3);
        System.out.println(tickets);
    }

    public static void printTotal(double ticketPrice, int tickets)
    {
        System.out.println(ticketPrice * tickets);
    }
}

public static void printArea(double length, double width)

public class ProduceCost
{
    public static void main(String[] args)
    {
        int boxes = 3;
        printCost(2.0, boxes + 1);
    }

    public static void printCost(double pricePerPound, int pounds)
    {
        System.out.println(pricePerPound * pounds);
    }
}

8.0

When you write Math.sqrt(49.0), how does Java know which method you mean, and whether your arguments are acceptable? It cannot read your mind or the method’s documentation comment. It needs a short, exact description of each method that it can compare against your call.

That description is the method signature: the method’s name together with the ordered list of its parameter types. For a method with no parameters, the signature is the name with an empty parameter list. To write a signature, start from the header and keep only the name and the parameter types, in order:

Notice what the signature leaves out: the return type, the parameter names, and public static. Why? Because a call does not show any of them. In printTotal(12.5, 3) you can see the name and the types of the values (a double, then an int), and nothing else. The signature holds exactly what Java can check against a call.

Arguments must match the signature

For a call to compile, its arguments must be compatible in number and order with the parameter types in the signature:

• Number: one argument for each parameter, no more and no fewer.
• Order: the first argument must fit the first parameter’s type, the second argument the second type, and so on.
• Compatible type: each argument must be a value that can be stored in that parameter. An int argument may go into a double parameter, because Java widens it automatically (Topic 1.5). A double argument may not go into an int parameter, because that could lose the decimal part.

System.out.println(Math.pow(2.0, 5.0));
System.out.println(Math.pow(5.0, 2.0));

32.0
25.0

Now change the argument’s type. sqrt’s parameter is a double, but here the argument is the int value 49:

System.out.println(Math.sqrt(49));

7.0

This compiles and runs. The int 49 is compatible with the double parameter, so Java widens it to 49.0 before the method starts. The rule is “compatible with” the parameter type, not “exactly the same as.”

Here is what happens when a call does not match the signature. Each of these fails to compile:

For a wrong number of arguments, the compiler also lists required: double and found: double,double: it is comparing the call to the signature, exactly as you would.

public class TicketSwapped
{
    public static void main(String[] args)
    {
        printTotal(3, 12.5);
    }

    public static void printTotal(double ticketPrice, int tickets)
    {
        System.out.println(ticketPrice * tickets);
    }
}

public class ProduceSwap
{
    public static void main(String[] args)
    {
        printCost(2, 1.5);
    }

    public static void printCost(double pricePerPound, int pounds)
    {
        System.out.println(pricePerPound * pounds);
    }
}

public class ProduceFixed
{
    public static void main(String[] args)
    {
        printCost(1.5, 2);
    }

    public static void printCost(double pricePerPound, int pounds)
    {
        System.out.println(pricePerPound * pounds);
    }
}

Here is a reasonable thing to try: write a method that adds 10 bonus points to a score, pass it your score variable, and expect your variable to go up by 10. Does it? To answer that, you need to know exactly what Java hands to a method when you pass a variable as an argument: the variable itself, or something else?

Building on 1.9.4: a parameter starts out holding the value of its argument, and an argument can be a variable.

In plain words: when you pass a variable, Java does not give the method your variable. It reads the value stored in your variable and gives the method a copy of that value. It is like photocopying your homework for a friend: if your friend scribbles on the copy, your original is untouched.

Java passes arguments using call by value: each parameter is initialized with a copy of its argument’s value. The parameter is a separate variable. Changing it inside the method changes only the copy.

public class BonusPoints
{
    public static void main(String[] args)
    {
        int myScore = 80;
        addBonus(myScore);
        System.out.print("Back in main: ");
        System.out.println(myScore);
    }

    public static void addBonus(int score)
    {
        score += 10;
        System.out.print("Inside addBonus: ");
        System.out.println(score);
    }
}

Inside addBonus: 90
Back in main: 80

Now change one thing: give main’s variable the same name as the parameter. Surely now they are the same variable?

public class SameName
{
    public static void main(String[] args)
    {
        int score = 80;
        addBonus(score);
        System.out.print("Back in main: ");
        System.out.println(score);
    }

    public static void addBonus(int score)
    {
        score += 10;
        System.out.print("Inside addBonus: ");
        System.out.println(score);
    }
}

Inside addBonus: 90
Back in main: 80

The output is identical. There are still two variables that happen to share a name: one declared on line 5 in main’s block, and one declared in addBonus’s header on line 11. Each method sees only its own. The call on line 6 copies the value 80 from one to the other, and that is the only connection between them.

public class Laps
{
    public static void main(String[] args)
    {
        int laps = 5;
        train(laps);
        laps += 1;
        System.out.println(laps);
    }

    public static void train(int laps)
    {
        laps *= 2;
        System.out.print("Trained: ");
        System.out.println(laps);
    }
}

Trained: 10
6

Some methods do something you can see, like printing. Others work out an answer that the caller needs to keep using: Math.sqrt computes a square root, and the program usually needs that number for something else. As 1.9.6 showed, a method cannot sneak an answer back by changing its parameter. So how does an answer get from the method back to the caller?

In plain words: some methods are like a doorbell: you press it, something happens, and you get nothing to hold. Others are like a calculator: you put numbers in and get a number back, and what you do with that number is up to you.

The return type in a method’s header (the word just before the name) says which kind the method is.

• A void method has the return type void. It does not give back any value. printTotal, printReminder, and System.out.println are void methods. Because there is no value, a call to a void method is used only as a statement on its own, never as part of an expression.
• A non-void method has any other return type, such as int, double, or String. It gives back a value, called its return value, of exactly that type. sqrt and pow return a double.

Inside a non-void method, a return statement such as return hours * 60; does two things: it sends the value back to the caller, and it ends the method, sending control back to the point of the call (1.9.3). Java then uses the returned value in place of the call, as if the call had been replaced by the value.

To use a return value, the caller must either store it in a variable (of a compatible type) or use it as part of an expression. Otherwise the value is simply thrown away.

double side = Math.sqrt(81.0);
System.out.println(side);
System.out.println(Math.abs(-15) + 5);

9.0
20

Now look at a non-void method from the inside, with its return statement, and watch the flow of control. minutesIn is a method written for this example.

public class MinutesReturn
{
    public static void main(String[] args)
    {
        System.out.println("Planning practice...");
        int total = minutesIn(2) + 15;
        System.out.println(total);
    }

    public static int minutesIn(int hours)
    {
        System.out.println("Converting hours to minutes");
        return hours * 60;
    }
}

Planning practice...
Converting hours to minutes
135

1. Line 5 prints the first line.
2. Line 6 starts evaluating minutesIn(2) + 15. Before it can add, it needs the value of minutesIn(2), so control jumps into the method with hours = 2.
3. Line 12 prints “Converting hours to minutes”.
4. Line 13 computes 2 × 60 = 120 and returns it. The method ends right there.
5. Control returns to the middle of line 6, exactly where the call was. The call is replaced by 120, so Java finishes 120 + 15 = 135 and stores it in total.
6. Line 7 prints 135.

The header promised an int (public static int minutesIn), and the returned value, 120, is an int. You are not expected to write methods like this yet; Unit 3 teaches that. For now, you need to read them.

public class VoidInExpression
{
    public static void main(String[] args)
    {
        double total = printTotal(12.5, 3);
    }

    public static void printTotal(double ticketPrice, int tickets)
    {
        System.out.println(ticketPrice * tickets);
    }
}

int temperature = -8;
Math.abs(temperature);
System.out.println(temperature);

int temperature = -8;
int degreesBelowZero = Math.abs(temperature);
System.out.println(degreesBelowZero);

public class PizzaOrder
{
    public static void main(String[] args)
    {
        int slices = slicesFor(3) + 1;
        System.out.println(slices);
    }

    public static int slicesFor(int people)
    {
        System.out.print("Ordering for ");
        System.out.println(people);
        return people * 2;
    }
}

Ordering for 3
7

You know that Math.abs(-15) returns 15, an int. But you can also find the absolute value of -7.5, and the answer, 7.5, is a double. One method cannot have a parameter that is both an int and a double, and it cannot return two different types. So how can abs handle both?

The answer: there are two methods named abs. The Math documentation lists both:

public static int abs(int a)
public static double abs(double a)

Their signatures are abs(int) and abs(double). The names match, but the parameter types differ, so the signatures are different. Methods are overloaded when there are several methods with the same name but different signatures.

When you call an overloaded method, Java compares your arguments with each signature and runs the one whose parameter list matches. This is why 1.9.5 defined a signature as name plus parameter types: the name alone is not enough to pick a method, but the name plus the types of the arguments is.

You have used an overloaded method since Topic 1.1 without knowing it. System.out.println has many versions, including println(int), println(double), println(String), and println() with no parameters, which is why it accepts whatever you give it.

System.out.println(Math.abs(-7));
System.out.println(Math.abs(-7.5));
System.out.println(Math.abs(-7.0));

7
7.5
7.0

Overloaded methods can also differ in how many parameters they have. The String documentation lists two substring methods, which give back part of a piece of text:

String substring(int beginIndex)
String substring(int beginIndex, int endIndex)

Their signatures are substring(int) and substring(int, int). A call with one int argument runs the first; a call with two runs the second. (A call to a String method is written after a piece of text, like word.substring(2, 5); Topic 1.14 teaches those calls, and Topic 1.15 teaches what substring does in detail.) Here is the same idea in a program you can trace, with two methods written for this example:

public class Receipt
{
    public static void main(String[] args)
    {
        printTotal(4.25);
        printTotal(4.25, 2);
    }

    public static void printTotal(double price)
    {
        System.out.println(price);
    }

    public static void printTotal(double price, int quantity)
    {
        System.out.println(price * quantity);
    }
}

4.25
8.5

Line 5 has one double argument, matching printTotal(double) on line 9. Line 6 has a double and an int, matching printTotal(double, int) on line 14, which prints 4.25 × 2 = 8.5.

public class SameSignature
{
    public static void main(String[] args)
    {
        System.out.println(half(9));
    }

    public static int half(int number)
    {
        return number / 2;
    }

    public static double half(int value)
    {
        return value / 2.0;
    }
}

Here is a program that uses every idea from this chapter. A teacher adds a 5-point curve to a quiz score, prints the original and the curved score, and then works out how far the curved score is from a goal of 90.

public class QuizReport
{
    public static void main(String[] args)
    {
        int quiz = 78;
        int curved = addCurve(quiz, 5);
        printScore(quiz);
        printScore(curved);
        int gap = Math.abs(curved - 90);
        System.out.print("Points from goal: ");
        System.out.println(gap);
    }

    public static int addCurve(int score, int points)
    {
        score += points;
        return score;
    }

    public static void printScore(int score)
    {
        System.out.print("Score: ");
        System.out.println(score);
    }
}

First, read the headers like documentation:

Now trace the flow of control. addCurve and printScore each have their own parameter named score; those are two separate variables, and neither one is quiz.

Score: 78
Score: 83
Points from goal: 7

What each idea contributed:

• Methods and flow of control (1.9.1, 1.9.3): addCurve and printScore run only when called, and after each one, control returns to the line it was called from.
• Procedural abstraction (1.9.2): line 9 uses Math.abs knowing only what it does.
• Parameters, arguments, and signatures (1.9.4, 1.9.5): each call passes values that match its signature in number, order, and type.
• Call by value (1.9.6): addCurve changed its parameter score to 83, yet quiz still printed 78.
• Return values (1.9.7): the curved score reached main only because addCurve returned it and line 6 stored it. printScore is void, so it is called as a statement.
• Overloading (1.9.8): abs(int) is chosen because curved - 90 is an int.

The Watch Out boxes explain each mistake. Use this table to look up a compiler message you see while working with methods.

One mistake has no message at all: calling a non-void method and ignoring its return value. The program compiles and runs, but the answer is lost. Store it or use it in an expression.

• A method is a named block of code that runs only when it is called. Thanks to procedural abstraction, you can use a method from its documentation, knowing what it does without knowing how it was written.
• A method call interrupts the normal top-to-bottom order: Java runs the method’s statements, then returns to the point immediately after the call (or to the middle of the expression the call is in).
• A method header lists the return type, the name, and the parameters. A method signature is just the name and the ordered parameter types, and a call’s arguments must match it in number, order, and type.
• Java uses call by value: each parameter gets a copy of its argument, so changing a parameter never changes the caller’s variable.
• A void method returns nothing and is called as a statement on its own. A non-void method returns a value of its return type, which the caller must store or use in an expression.
• Methods are overloaded when they share a name but have different signatures; Java picks the version whose parameter types match the arguments.

public class Bakery
{
    public static void main(String[] args)
    {
        int muffins = 4;
        int boxes = boxesNeeded(muffins);
        System.out.println(muffins);
        System.out.println(boxes);
        printLabel(boxes);
    }

    public static void printThanks()
    {
        System.out.println("Thank you!");
    }

    public static int boxesNeeded(int count)
    {
        count += 2;
        System.out.println("Packing");
        return count / 3;
    }

    public static void printLabel(int boxes)
    {
        System.out.print("Boxes: ");
        System.out.println(boxes);
    }
}

Packing
4
2
Boxes: 2

public class MuffinCost
{
    public static void main(String[] args)
    {
        double total = 0.0;
        costFor(4);
        System.out.println(total);
    }

    public static double costFor(int muffins)
    {
        return muffins * 1.5;
    }
}

public class MuffinCostFixed
{
    public static void main(String[] args)
    {
        double total = 0.0;
        total = costFor(4);
        System.out.println(total);
    }

    public static double costFor(int muffins)
    {
        return muffins * 1.5;
    }
}

public static void printTotal(double price, int quantity)
public static void printTotal(int quantity, double price)

public class OrderOverload
{
    public static void main(String[] args)
    {
        printTotal(3, 9.5);
    }

    public static void printTotal(double price, int quantity)
    {
        System.out.println("Version 1");
    }

    public static void printTotal(int quantity, double price)
    {
        System.out.println("Version 2");
    }
}

public class TripleIt
{
    public static void main(String[] args)
    {
        int a = 5;
        int b = triple(a);
        System.out.println(a);
        System.out.println(b);
    }

    public static int triple(int n)
    {
        n *= 3;
        return n;
    }
}

public static double average(int first, int second)

Check each statement. If the answer is “not yet,” reread the linked subsection.

• I can explain what a method and a block are, and why a method that is never called never runs. Reread
• I can explain how documentation lets me use a method without knowing how it was written. Reread
• I can trace a program into a method and back to the point right after the call. Reread
• I can name the return type, name, and parameters in a header and match arguments to parameters. Reread
• I can write a method signature and decide whether a call matches it in number, order, and type. Reread
• I can explain why changing a parameter does not change the caller’s variable. Reread
• I can tell void from non-void methods and use a return value by storing it or using it in an expression. Reread
• I can decide whether two methods are overloaded and predict which version a call runs. Reread