Give a piece of work a name

You've already asked someone else to do work for you. Every time you typed System.out.println("hi"), you were handing a job to code somebody else wrote and named. You didn't open it up. You didn't read it. You said its name, gave it a word, and it printed. Today you get to be that somebody else.

This is the chapter where your programs stop being one long list of instructions. It's also where you meet the wall of red text Java prints when a program dies. That wall isn't noise. It's a map.

By the end of this page

• Write a piece of work once, give it a name, and use it as many times as you like.
• Say exactly what a method hands back, and what it takes in.
• Draw the stack of plates Java keeps in memory while your program runs.
• Read a real crash report top to bottom and point at the line that broke.
• Break Java in a brand new way, on purpose, and explain why it broke.

Section 1The same five lines, three times over

Here's a small program. It prints three boxes: one for a high score, one for a new round, one for game over. Read it and notice how you feel about it.

// The annoying version. Same five lines, three times over.
public class Repeat {
    public static void main(String[] args) {
        System.out.println("+----------------+");
        System.out.println("|   HIGH SCORE   |");
        System.out.println("+----------------+");

        System.out.println("+----------------+");
        System.out.println("|   NEW  ROUND   |");
        System.out.println("+----------------+");

        System.out.println("+----------------+");
        System.out.println("|   GAME  OVER   |");
        System.out.println("+----------------+");
    }
}

Every line here is one you already know. Almost. Let's pay off two words you've been typing since your very first program. Nobody has told you what they mean yet.

A class is a named design for code and data that belong together. Not a box, not a folder — a design, like a blueprint for a house. Java insists that every method live inside one, so there's nowhere else main could go. Without a class the file won't compile at all. Right now that's honestly all a class does for you. Phase 1 is where classes become the whole point, because that's where you start building things from the design.

public answers a different question: who's allowed to use this? It means "anybody". Take it off main and your file still compiles fine. I tried it. But the java command then can't find main, so it prints Main method not found and quits. Deciding who may use what is called access control. It only starts to earn its keep in Phase 1, when you have classes with parts worth keeping private.

The rest you've met. main is the block Java starts running first. Each println prints one line of text and then moves to the next line. Nine calls. Three of them are identical to three others.

Now imagine your boss walks in and says the boxes should use = signs instead of dashes. You have to change six lines. You'll get five of them right. That sixth one will sit there looking slightly wrong for a month. This is not a made-up worry. It's the most common way real programs get bugs.

That card is what we're about to build. Java calls it a method: a named piece of work you can ask for by name. Below is the very same program with a card called banner.

// The same output, but the work has a name now.
public class Named {

    static void banner(String text) {
        System.out.println("+----------------+");
        System.out.println("|   " + text + "   |");
        System.out.println("+----------------+");
    }

    public static void main(String[] args) {
        banner("HIGH SCORE");
        banner("NEW  ROUND");
        banner("GAME  OVER");
    }
}

Line by line. static void banner(String text) is the top of the card. It says the card is called banner. It also says whoever uses it must hand over one piece of text. The three println lines inside the curly brackets are the work on the card. The middle one glues your text into the middle of the box using +, which joins text together. Then main says the card's name three times, each time with different text.

+----------------+
|   HIGH SCORE   |
+----------------+
+----------------+
|   NEW  ROUND   |
+----------------+
+----------------+
|   GAME  OVER   |
+----------------+

Section 2Reading a method, word by word

Methods have a fixed shape, and every word in that shape is doing a job. Let's take one apart. Below is a method that doubles a number.

static int doubled(int number) {
    int answer = number * 2;
    return answer;
}

Five words on that first line, and each one is a separate promise.

• static — you've typed this in every program so far, so here's the honest answer. It means this method belongs to the class itself, rather than to any individual thing built from the class. Delete it and the program won't compile. Here's exactly why. main runs before a single thing has been built. So a non-static method would have nothing to belong to. Java won't guess, so it says non-static method greet() cannot be referenced from a static context. The full story lands in chapter 1.2, once you can build things and see the difference.
• int here is the return type — the kind of value this method hands back when it finishes. This one hands back a whole number.
• doubled is the name. You choose it. Java doesn't care what it means. You will, in three weeks, at 1am.
• (int number) is the parameter list — the boxes the method needs filled in before it can start. This method needs exactly one whole number, and inside the method that box is called number.
• Everything between { and } is the body: the actual work.

Inside the body, int answer = number * 2; makes a fresh box called answer and puts double the number in it. Then return answer; does two things at once, and both matter. It hands the value in answer back to whoever asked. And it stops the method immediately. Any lines after a return never run.

Why the immediate stop? Because handing back the answer is the method finishing. The method was asked one question, and it just answered it, so there's no one left to work for. Think of return as the door, not a note on the desk.

Now the other kind. Some work doesn't produce a value at all. The work happens, and nothing comes back. Printing is like that. You don't want a number back from a print. You want the words on the screen.

static void shout(String word) {
    System.out.println(word.toUpperCase() + "!");
}

The return type here is void, which is Java's way of saying this hands nothing back. Not zero. Not empty text. Nothing at all. The body has one line, and it does three things. word.toUpperCase() makes an ALL-CAPS copy of the text. + "!" sticks an exclamation mark on the end. Then println prints the result. There is no return here, because there's nothing to hand back. When the body runs out of lines, the method is done.

Hold on, though. Where did toUpperCase come from? Nobody wrote it in your file. Look at the dot, because the dot is the whole answer. doubled(21) is a method you call by name, on its own. word.toUpperCase() is a method you call on a thing, and the dot means "ask this particular piece of text".

So yes. Every piece of text in Java shows up with a pile of methods already stuck to it. toUpperCase is one of them. You never made it. It arrived with the text. That's what System.out.println has been doing all along, too. out is a thing that knows how to print, and println is one of its own methods. Phase 1 explains why things carry their own methods around like this. It's where the dot stops looking like punctuation and starts looking like the point.

int x = doubled(21);
System.out.println(x);
System.out.println(doubled(5) + doubled(5));
shout("hello");

42
20
HELLO!

MissingReturn.java:7: error: missing return statement
    }
    ^
1 error

VoidInPrintln.java:10: error: 'void' type not allowed here
        System.out.println(shout("hello"));
                                ^
1 error

Section 3The box gets a copy, not the box

Two words that sound like the same word, and aren't. The names in the method's brackets when you write it are the parameters. The actual values you hand over when you use it are the arguments. In doubled(int number), number is the parameter. In doubled(21), the 21 is the argument.

Now the part that matters. When you pass an argument, the method's parameter box gets a copy of the value. It does not get your box. Read this program, then bet on the answer.

static void addTen(int n) {
    n = n + 10;
    System.out.println("inside addTen, n is " + n);
}

public static void main(String[] args) {
    int score = 5;
    addTen(score);
    System.out.println("back in main, score is " + score);
}

main makes a box called score holding 5. It calls addTen(score). Inside, n = n + 10; writes 15 into n, and the next line prints it. Then we're back in main, which prints score.

inside addTen, n is 15
back in main, score is 5

Remember this one. In Phase 1 we meet a kind of value where the copy behaves very differently. The whole surprise depends on you being solid on this page first.

Section 4Variables born inside a method die inside it

A variable you declare inside a method exists only while that method is running, and only inside it. The word for "the region of code where a name means something" is scope. A variable declared in a method body has scope of exactly that body.

You have a file in your src/ that's meant to fail. makeSecret declares secret inside itself. Then main tries to print it.

static void makeSecret() {
    int secret = 99;
    System.out.println("made a secret: " + secret);
}

public static void main(String[] args) {
    makeSecret();
    System.out.println(secret);
}

Notice makeSecret() has empty brackets. A method is allowed to need nothing. It makes secret, prints a message using it, and finishes. Then main asks for secret — and here's what Java says.

ScopeBroken.java:13: error: cannot find symbol
        System.out.println(secret);
                           ^
  symbol:   variable secret
  location: class ScopeBroken
1 error

Read that carefully, because it's a friendly error. cannot find symbol means "you used a name I've never heard of". symbol: variable secret names the word it couldn't find. location: class ScopeBroken says where it looked. The little ^ points at the exact spot. Java isn't being difficult. From main's point of view, the word secret has never existed.

This is why return exists. If main needs the secret, the method must hand it back.

Section 5The stack of plates

This is the question the whole chapter has been building to. Say main has a variable called n. A method it calls has its own n. That method calls a third one, which also has an n. How does Java keep them straight?

That spike is called the call stack, and each plate is a frame. A frame holds one running method's own copies of its own variables. This is the real machinery. Everything about scope, copies and returns falls out of it.

Here's a tiny program with three methods and three variables all called n. It's deliberately confusing to read. And it isn't confusing at all once you can see the plates.

// Three methods, each with its own local variable called "n".
public class Frames {

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

    static int tripleThenAddOne(int n) {
        int t = triple(n);
        return t + 1;
    }

    public static void main(String[] args) {
        int n = 4;
        int answer = tripleThenAddOne(n);
        System.out.println("n is still " + n);
        System.out.println("answer is " + answer);
    }
}

triple takes a number, multiplies it by three into a box called out, and hands out back. tripleThenAddOne takes a number, asks triple for the answer, keeps it in t, and hands back t + 1. main puts 4 in its own n, asks tripleThenAddOne, and prints both its n and the answer.

Now step through it. Take your time on this one — click through every step. This picture is the thing you're actually here to learn.

n is still 4
answer is 13

Section 6Reading the wall of red text

Now the payoff, and it's a big one. When your program dies, Java prints the call stack. The whole spike, plate by plate, exactly as it was at the moment things went wrong. That printout is called a stack trace, and most beginners scroll past it in a panic. You're not going to, because you now know what a stack is.

Let's break something on purpose, deep down. Three methods, each calling the next.

// Blows up on purpose, three calls deep, so we can read a real stack trace.
public class Boom {

    static int divide(int top, int bottom) {
        return top / bottom;
    }

    static int average(int total, int count) {
        return divide(total, count);
    }

    static void report(int total, int count) {
        System.out.println("about to work out the average");
        System.out.println("average is " + average(total, count));
    }

    public static void main(String[] args) {
        report(60, 0);
    }
}

divide takes two whole numbers and hands back the first divided by the second. Notice it has two parameters, separated by a comma — methods can take as many as you like. average passes its two numbers straight on to divide. report prints a message, then prints whatever average hands back. main calls report(60, 0). Sixty divided by zero. In maths that has no answer. In Java it's a crash.

about to work out the average
Exception in thread "main" java.lang.ArithmeticException: / by zero
	at Boom.divide(Boom.java:5)
	at Boom.average(Boom.java:9)
	at Boom.report(Boom.java:14)
	at Boom.main(Boom.java:18)

Now let's read it properly, because you'll use this skill for the rest of your life.

• about to work out the average printed fine. So the program got at least that far. Useful already.
• Exception in thread "main" — an exception is Java's word for "something went wrong and I'm stopping". thread "main" means it happened in the main run of your program.
• java.lang.ArithmeticException: / by zero — the kind of problem, then a plain English hint. Java literally told you the answer. Read this bit before you read anything else.
• at Boom.divide(Boom.java:5) — this is where it blew up. Class Boom, method divide, file Boom.java, line 5. Go and look at line 5. That's the top plate.
• The three lines below it are who asked, in order. Line 9 of average called divide. Line 14 of report called average. Line 18 of main called report.

So the trace answers two different questions. The top line says where. The lines under it say how we got there. And the real bug here is not on line 5 at all — dividing is fine. The bug is line 18, where somebody passed a count of zero. You found it by reading downwards.

Section 7Running out of plates

Time to break Java in a way you haven't seen yet. What happens if a method calls itself? Not a copy of itself — itself, by name, with nothing to stop it.

public class ForeverRecursive {

    static void dig() {
        dig();
    }

    public static void main(String[] args) {
        System.out.println("digging...");
        dig();
        System.out.println("this line never runs");
    }
}

Four lines of real work. dig takes nothing, hands nothing back, and its entire body is a call to dig. main prints a word, calls dig, and has a line afterwards that we've cheekily labelled.

digging...
Exception in thread "main" java.lang.StackOverflowError
	at ForeverRecursive.dig(ForeverRecursive.java:5)
	at ForeverRecursive.dig(ForeverRecursive.java:5)
	at ForeverRecursive.dig(ForeverRecursive.java:5)
	at ForeverRecursive.dig(ForeverRecursive.java:5)
	at ForeverRecursive.dig(ForeverRecursive.java:5)
… and ForeverRecursive.dig(ForeverRecursive.java:5) about a thousand more times. I trimmed it.
   Java stops printing the trace after 1024 lines, so even the printout gives up.

How many plates fit? HowDeep.java catches the crash and counts. On this machine, two runs in a row gave ran out of room after 45683 calls and ran out of room after 47594 calls. Your number will differ, and differ again next time. The exact height is not a promise Java makes.

So a method calling itself is a disaster. Except it isn't. It's one of the most elegant tools you have, and the only thing missing above was a way to stop.

static void countdown(int n) {
    if (n == 0) {
        System.out.println("Liftoff!");
        return;
    }
    System.out.println(n);
    countdown(n - 1);
}

Line by line. if (n == 0) checks for the finish. If we're there, print Liftoff! and return. That's return in a void method with no value after it. Java allows that, and it means "I'm done, leave now". If n isn't 0, print it, then call countdown again with a smaller number. Smaller every time, so it must eventually hit 0.

Now you've seen it work, here's the word: a method that calls itself is doing recursion. The if that stops it is the base case. Recursion without a base case is ForeverRecursive.java. Recursion with one is a countdown, and each nested call is one more plate that gets binned on the way back down.

static int factorial(int n) {
    if (n <= 1) {
        return 1;
    }
    return n * factorial(n - 1);
}

Factorial of 5 means 5 × 4 × 3 × 2 × 1. The base case says factorial of 1 (or less) is 1. Otherwise, hand back n times the factorial of one less. Read that last line as a sentence and it's almost the maths definition. Running java CountdownRecursive gives 3, 2, 1, Liftoff!, then 5 factorial is 120.

Section 8One name, several shapes

You've been using this since your first program and never noticed. System.out.println works on text. It works on whole numbers. It works on decimals. How can one method take all of those? It can't. There are lots of methods, all called println, each taking a different kind of thing. That's overloading: same name, different parameter list.

static void show(int n)            { System.out.println("an int: " + n); }
static void show(double d)         { System.out.println("a double: " + d); }
static void show(String s)         { System.out.println("a String: " + s); }
static void show(int a, int b)     { System.out.println("two ints: " + a + " and " + b); }

Four methods, one name. Java picks which one you meant by looking at what's in your brackets: how many things, and what kind. The return type isn't part of the decision — only the parameters. Now the last call in main is show('A'), with single quotes. That's a char — a single character. And no show(char) exists.

an int: 7
a double: 7.5
a String: seven
two ints: 7 and 8
an int: 65

Section 9The guessing game, with names

Go and look at src/GuessOld.java. It's the guessing game from 0.3, secret fixed at 42 so your runs match this page. Everything is in one lump inside main: the rules, the loop, the reading, the range check, the hints, the ending. Thirty-odd lines you have to read all of to understand any of.

Nothing in it is wrong. It doesn't say anything, though. Compare the middle of GuessNamed.java:

printRules();

while (tries < 5) {
    int guess = askForGuess();
    tries = tries + 1;

    if (isSilly(guess)) {
        System.out.println("That is not between 1 and 100.");
    } else if (guess == secret) {
        System.out.println("Got it in " + tries + " tries!");
        won = true;
        break;
    } else {
        giveHint(guess, secret);
    }
}

You can read that out loud and it's nearly English. Print the rules. While there are tries left, ask for a guess. If the guess is silly, say so. If it's the secret, celebrate and stop. Otherwise give a hint. Four method names — printRules, askForGuess, isSilly, giveHint — and the shape of the game is visible at a glance.

Two of those are worth a second look. askForGuess is static int askForGuess(): no parameters, but it hands back an int. It prints the prompt and returns whatever was typed. And isSilly returns boolean — true or false. A method that hands back a yes-or-no is how you give a condition a name. Your if then reads like a sentence instead of a puzzle.

I picked a number from 1 to 100.
You get 5 guesses.
Guess: Too high.
Guess: Too low.
Guess: That is not between 1 and 100.
Guess: Got it in 4 tries!

Identical behaviour to the old version, and the new one is easier to change. Want three guesses instead of five? One number. Want a different hint? One method. That's the win.

Section 10Three questions

Section 11What broke, and what surprised you

Write down two things before you move on. The error message you saw the most today, in your own words. And the moment you thought Java would do one thing and it did another.

If an int: 65 was your moment, good — that's Java making a quiet decision for you. Spotting those is most of what getting good at this means. If your moment was score is 5, hold on to it. Phase 1 turns that one upside down.

Next up: one name holding many values at once, and what happens when you ask for the twenty-first item in a list of twenty.