What a Program Is

Outcome: read a short program and say, in ordinary words, what each line contributes to the result you see.

Prerequisite: none. This page assumes you have never written a program. If you already program, skip ahead to First Program.

A program is a description, not an instruction shouted at a machine

People often picture programming as commanding a computer. It is closer to writing a description so precise that following it leaves no room for interpretation. You write down what things are and how a result is obtained. The machine follows the description exactly, including the parts you got wrong.

That last clause is the whole craft. A machine cannot guess what you meant. Everything you learn about a language is really about saying what you mean without leaving gaps.

Four ideas cover most of it

Almost every program you will ever read is built from four ideas.

A value is a piece of data. The number 45, the text "study plan", the answer true.

A name points at a value so you can refer to it later. Writing let total = 45 gives the value 45 the name total.

A function is a named calculation. You hand it values, it hands back a value. It exists so a calculation can be written once and used in many places.

A run is the moment the description is followed and produces something you can observe.

Here are all four in one file.

TOPAZ

function minutesLeft(total: int, spent: int) -> int {
    total - spent
}

let plan = "study plan"
let total = 45
let spent = 20

print("{plan}: {minutesLeft(total, spent)} minutes left")

If Topaz is already installed, save it as what-a-program-is.tpz, then check it and run it with the commands below. Otherwise, read along for now; First Program installs the tool before asking you to type your own file.

BASH

topaz check what-a-program-is.tpz
topaz run what-a-program-is.tpz

The observed result is:

Output

study plan: 25 minutes left

Read the result backwards into the code

Start from the output and walk back. The text study plan came from the name plan, which points at the value "study plan". The number 25 was not written anywhere. It was calculated by minutesLeft from 45 and 20.

Look at the function once more. Its first line states a contract. It takes two whole numbers called total and spent, and it promises to give back a whole number. The body is a single expression, total - spent, and that expression becomes the answer. Nothing else in the file can change what that function does, because everything it needs arrives through its two parameters.

That property is worth naming. A calculation that depends only on what you hand it is one you can reason about alone, without holding the rest of the program in your head.

Why the check step exists

You ran two commands, not one. The check reads your description and looks for gaps before anything runs. If you wrote minutesLeft(total) and forgot the second value, the check says so and names the place. The run never starts.

Some environments discover a missing argument only when that call runs, while statically checked languages can catch it earlier. Topaz makes that early answer an explicit command you can run before execution, so check comes first in every example you will read here.

Try this

Change spent to 50, leaving everything else alone. Predict the output before you run it.

Answer

The line becomes study plan: -5 minutes left. The subtraction is followed exactly as written, and nothing in the description says a result must be positive. If negative minutes would be wrong for your purpose, that rule has to be written down too. This is the whole lesson in one line, the machine follows what you said rather than what you meant.

Ready to continue when

You can point at a value, a name, a function signature, the expression that produces its result, and explain what the check command does that the run does not.

Install the toolchain and write your own first file in First Program. If you already know another language, Coming From Other Languages maps what you know onto what you just read.