What a Program Is

Outcome: Read a short program and explain how each line contributes to the observed output.

Prerequisite: None. This guide assumes no prior programming experience. Experienced developers can skip directly to First Program.

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

Programming is often perceived as commanding a computer step by step. In practice, it resembles writing a precise specification that eliminates ambiguity. You define entities such as values and functions, and specify how results are derived from those inputs. The runtime engine does not guess what outcome you intended. It executes this written specification literally, including any errors in logic.

That final point defines software development. An execution engine cannot infer developer intent or correct mistaken assumptions automatically. Computers follow the given rules and definitions without applying human intuition. Learning a language involves expressing precise logic without unintended ambiguities, ensuring that the specification matches the intended goal.

Four ideas cover most of it

Most programs are constructed from four core concepts. Understanding how these four elements work together allows you to read code by identifying what data exists and how it moves through the system.

A value represents data, such as the integer 45, the string "study plan", or the boolean true. Values are the concrete pieces of information that a program evaluates and displays. In the example code below, "study plan", 45, and 20 are values defined on lines 5, 6, and 7.

A name references a value for subsequent use. For example, writing let total = 45 binds the identifier total to the value 45. Naming values prevents repeating raw data throughout a file and makes the code readable. In lines 5 through 7, plan, total, and spent are names created to hold data for later calculation.

A function is a named unit of computation. It accepts input values and returns a result, allowing calculation logic to be defined once and reused across a codebase. Lines 1 through 3 define the minutesLeft function, which receives inputs and computes the difference total - spent.

A run is the execution of the program description to produce observable output. During a run, the system evaluates expressions line by line to produce final results. Line 9 executes during a run to combine the function output with strings and display the final text on the screen.

The following example combines all four concepts in a single file.

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 installed, save the code as what-a-program-is.tpz, then check and run it using the commands below. Otherwise, review the explanation for now. The First Program section covers toolchain installation prior to writing custom files.

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

The command produces the following output:

study plan: 25 minutes left

Read the result backwards into the code

Start from the output and trace it back to the source. The printed output study plan: 25 minutes left is constructed from separate pieces evaluated during execution. The string study plan originates from the variable plan, which references "study plan". The numeric value 25 is not hardcoded inside the print statement; it is dynamically evaluated by minutesLeft from inputs 45 and 20.

Look at the function definition again. The signature shows total: int, spent: int and -> int. The : int following a name indicates that an integer value is expected in that position, while -> int indicates that the function returns an integer. Detailed rules for type annotations are covered formally in the next lesson. Understanding their basic role is sufficient for now. The signature establishes its input and output contract, accepting two integer parameters total and spent and declaring an integer return type.

The body of the function consists of a single expression, total - spent, which evaluates to the final result of 25. In Topaz, the evaluation of this body expression determines the return result. External context cannot alter function behavior, as all dependencies are passed explicitly through parameters.

This property provides isolated reasoning. A computation that depends solely on explicit inputs can be evaluated independently, without requiring knowledge of global program state. When reading or writing functions, examining the declared inputs and the body expression is sufficient to predict what the function will return.

Why the check step exists

The workflow uses two commands to separate description analysis from execution. The check step analyzes the program description and identifies missing inputs before execution. If minutesLeft(total) is called without the second argument, the check reports the error location and halts execution before the run begins. This prevents the program from executing with missing arguments.

Some environments detect missing arguments only during execution when that line is reached, whereas statically checked languages identify them earlier. Topaz exposes this validation as an explicit command prior to execution, which is why check precedes run throughout these guides. Checking the code first gives immediate feedback on structural errors before running the application.

Try this

Change spent to 50 while leaving other values unchanged. Predict the output prior to running the code.

Ready to continue when

You can identify a value, a name, a function signature, and its result expression, while explaining the operational difference between the check and run commands.

Install the toolchain and write a first program in First Program. Developers familiar with another language can review Coming From Other Languages to map existing knowledge to these concepts.