Before we write any code

Imagine you ask a friend to make you a cup of tea. Forty minutes later they come back holding a kettle stuffed with tea bags and no water at all. You'd assume they were joking. A computer is not joking. A computer is the most literal thing you will ever meet. Learning to program is mostly learning to say what you actually mean.

That's the whole job. Not maths. Not typing fast. Not memorising a thousand words. Saying exactly what you mean, in an order that works, to something with no common sense whatsoever.

So we are not going to write Java yet. First we'll get you comfortable in the room where the work happens. Skip this page and every later page quietly assumes you already know these moves. Then you lose an hour to something that was never the lesson.

Wait — what is Java actually for?

Fair question, and most courses never answer it. Java is a language for writing instructions. What those instructions do is up to you.

Real things people build with it: Android apps, the software banks run on, huge chunks of Netflix and Amazon, Minecraft, and most of the invisible machinery behind websites — the part that remembers your account and takes your money. It runs on everything from a phone to a server the size of a fridge.

What you'll build in this course, in order: a program that prints one line. A game where the computer guesses your number in seven tries. A word counter that reads a real file. Then a playable Wordle, in your terminal, with the colours. That's the end of the first phase, and you'll have written every line of it.

After that it gets more serious — a web server, a database, a program that runs other programs. But that's months away, and none of it works without today.

What you'll be able to do at the end

• Explain, in your own words, what a program is — and why computers take things so literally.
• Open a terminal without feeling like you've broken into something.
• Move around your own computer by typing, using five commands.
• Check that the Java toolbox is installed and working.
• Make a file, save it, and ask your computer to print it back at you.

Section 1A program is a recipe. The cook has no common sense.

A program is exactly that — a list of steps, written down, that a machine carries out. The word "code" means those steps written in a language the machine's tools can deal with. Nothing more mysterious than that.

But there is one difference, and it is the difference that will define your next few months. A human following a recipe fills in the gaps. If the recipe says "add the eggs" and you have eggs in shells, you crack them. Nobody wrote "crack them". You just knew.

A computer never fills in a gap. Ever. It does exactly the steps, in exactly the order. And if you left out "crack them"? It puts whole eggs in the bowl and carries on cheerfully. It will not stop and ask. It will not think "hmm, that seems odd".

This is also, weirdly, the good news. A machine with no common sense is also a machine with no moods. It doesn't get bored on step 400. It doesn't do it differently on a Tuesday. Give it the same steps and the same starting point and you get the same result, every single time, forever. That reliability is the thing you'll lean on when you're hunting a bug at midnight.

Section 2Files, folders, and what "saving" actually means

You've used files for years. Let's make sure we mean the same thing by the word. In a few minutes you'll be talking to your computer about them directly.

A file is a named lump of information stored on your computer's disk. A photo is a file. A song is a file. A shopping list you typed is a file. From your computer's side there is no difference between those three. They are all long lines of numbers with a name attached. The name is what lets you find it again.

A folder — sometimes called a directory, same thing, different decade — is a named box that holds files. It can also hold other folders. That last part is the important bit. Folders inside folders inside folders is how your entire computer is arranged. It's one giant tree of boxes.

That full route has a name: it's called a path. A path is a set of directions to one exact spot. You will type paths constantly. So say this out loud once: the slashes separate the boxes. The last piece is the actual file.

Saving is not automatic, and this trips up everyone

Here's a thing nobody explains. When you open a file and start typing, you are not editing the file. You're editing a copy, held in memory.

Your computer keeps things in two separate places, and the difference matters enormously here. Memory is the fast, temporary one. It holds whatever the computer is thinking about right now, and it empties completely the moment the power goes off. The disk is the slow, permanent one. It keeps things while the machine is switched off, which is why your photos are still there tomorrow.

Memory is what you're holding in your head. The disk is a notebook you write in. Typing into an editor only changes what's in your head — nothing reaches the notebook until you save.

The file on the disk still says the old thing. It says the old thing right up until the moment you save. Saving means "take what's in memory and write it over the file on the disk". That's it. That's all saving is: copying from the forgetful place to the permanent place.

Section 3The terminal is not hacker stuff

Right now, when you want your computer to do something, you point at a picture and click it. That click is you giving an instruction: open this, run that. You've been programming your computer with your finger this whole time. You only ever had a menu of choices someone else drew for you.

The terminal is the same conversation, typed. It's a window where you type the name of an instruction and press Enter. Your computer does it, then types back. That's the entire idea. A window for typing instructions instead of clicking them.

Why do programmers live in there? Three honest reasons.

One: most programming tools have no icon at all. The tool that turns your Java text into a running program is called javac. It has no window, no buttons, nothing to double-click. It exists only as a name you can type. If you can't type, you can't reach it.

Two: typed instructions can be written down and repeated. "Click the third menu, then the button on the left" is a story you have to re-tell. But javac Hello.java is a thing you can save in a file. You can hand it to a colleague, or run it automatically at 3am. This is a much bigger deal than it sounds.

Three: the terminal tells you what went wrong. When a click fails you often get a shrug and a beep. When a typed command fails, you usually get a paragraph explaining what it tried and where it stopped. Those paragraphs look intimidating for about a week, and then they become the most useful text on your screen.

Open it now

On a Mac: press ⌘ + Space, type "Terminal", press Enter. On Windows: open Git Bash from the Start menu, or start WSL — see the box above. On Linux you already know, or Ctrl+Alt+T works nearly everywhere.

You'll get a mostly-empty window with a line of text ending in something like $ or %. That symbol is called the prompt, and it means "I'm ready, type something". Throughout this course, when you see $ at the start of a code line, that's the prompt. Don't type the $ itself. Everything after it is yours to type.

Section 4Is the toolbox even there?

Java needs two tools installed on your machine. They arrive together in a bundle called the JDK — the Java Development Kit. That's a grand name for "a box with the Java tools in it". Chapter 0.1 is entirely about what each tool does and why there are two. For now we only want to know they exist.

The trick for checking is that most command-line tools will tell you their version number if you ask politely. So we ask both of them.

$ java -version
openjdk version "17.0.17" 2025-10-21 LTS
OpenJDK Runtime Environment Zulu17.62+17-CA (build 17.0.17+10-LTS)
OpenJDK 64-Bit Server VM Zulu17.62+17-CA (build 17.0.17+10-LTS, mixed mode, sharing)

$ javac -version
javac 17.0.17

$ javcac -version
zsh: command not found: javcac

Section 5Five commands you'll type ten thousand times

Every command you type gets carried out somewhere. Not everywhere — somewhere. The terminal always sits inside exactly one folder. That folder is called the current folder, or "working directory" — same thing. It's the terminal's idea of where it's standing.

Almost every command acts on the current folder by default. If you say "list the files", it lists the files here. If you say "read note.txt", it looks for note.txt here, and nowhere else. It won't go hunting. Remember the recipe with no common sense.

Here are the five commands. Read the table, but the real learning is in the walkthrough underneath it.

Two of those need a word of explanation. The command mkdir is pronounced "make dir". It takes the name you want as an extra word after it. That extra word has a name: an argument, which means "the thing you're giving the command to work on". And .. — two dots — is a shorthand that every command understands. It means "the folder one level up", the box this box is sitting in. So cd .. is "step out".

$ pwd
/Users/you

$ ls
Desktop    Documents    Downloads    Music    Pictures

$ mkdir practice
$ ls
Desktop    Documents    Downloads    Music    Pictures    practice

$ cd practice
$ pwd
/Users/you/practice

$ ls
$ 

$ cd ..
$ pwd
/Users/you

$ pwd
/Users/you
$ cat note.txt
cat: note.txt: No such file or directory
$ ls -l practice
total 8
-rw-r--r--  1 you  staff  38  5 Sep 05:56 note.txt

Try all five right here, before you touch your own terminal

Below is a pretend terminal. It lives on this page, it cannot break anything, and it answers the way a real one would — same replies, same error messages. Nothing you type here touches your computer.

Use it to get the five commands into your fingers. Try this exact sequence, and read each answer before typing the next:

1. pwd — where am I?
2. ls — what's here?
3. mkdir practice — make a folder. Notice it says nothing back.
4. ls — now what's here?
5. cd practice then pwd — did the answer change?
6. cd .. then pwd — and back again.
7. cat notes.txt — read a file.

Then go off the script. Type a command that doesn't exist. Try cd nowhere. Try cat missing.txt. Those error messages are the ones you'll meet for real, so meeting them now — where nothing is at stake — is time well spent. Press the up arrow to bring back what you typed before.

Section 6Your editor — and why Word is the wrong tool

Java code is text. Plain text. Letters, digits, brackets, spaces — and absolutely nothing else. So you need a program that writes plain text and nothing else. That program is called a text editor.

Word is not one, and neither is Google Docs or Apple's Pages. Those are word processors, and the difference is not snobbery — it's that they secretly add things. Turn on the invisible marks in a Word document and look. You'll find instructions about fonts, sizes, margins and colours wrapped around every letter. Wonderful for an essay. Poison for code, because javac reads those instructions as part of your program. It has no idea what to do with them.

Use a real text editor instead. They're all free. VS Code is the common choice and it understands Java. Sublime Text is good too. On a Mac even TextEdit works, as long as you switch it to plain text first. That's Format → Make Plain Text. What you want from an editor is boring honesty. What you type is exactly what lands in the file.

One more thing to know about file names. A file extension is the bit after the dot — the .txt in note.txt, the .java in Hello.java. It's a label saying what kind of file this is. Tools take it seriously — javac will refuse a file that doesn't end in .java. So when your editor asks where to save, check the name it's about to use, every time.

Section 7Closing the loop

Time to put the two halves together. So far you have an editor (which makes files) and a terminal (which does things with files). The whole rest of this course is those two things passing work back and forth.

We need one more command: cat. It's short for "concatenate", which means "join things end to end" — a terrible name, because joining is not what you'll use it for. All you need to know is this: cat somefile prints that file's contents into your terminal. It's how you check what a file really says, rather than what your editor claims it says.

$ ls
note.txt
$ cat note.txt
Today I opened a terminal on purpose.
$ 

Section 8Check yourself

Section 9What broke, and what surprised you

This section is yours, and it's not filler. Somewhere in the last twenty minutes something didn't go the way this page said it would. A command not found. An editor that saved your file somewhere you didn't expect. A version number that starts with a different digit. A path with a space in it that behaved oddly.

Write it down — in a real note, in your own words. Not "it didn't work". Something more like: "I ran cat note.txt, expected my sentence, got No such file or directory. Turned out I was one folder up." That sentence, written by you, is worth more than this entire page. It's a bug report about your own mental model. That's how you stop making the same mistake twice.

Then answer these three without scrolling up. In your own words, not this page's words:

1. What is a program, and what's the one thing it will never do for you?
2. What did cd practice actually change, and how would you prove it?
3. Why is a word processor the wrong tool for writing code?