Platform Engineering · Lesson F02

Software: Instructions, Not Magic

The box from the last lesson does nothing on its own. It waits. Software is the list of instructions that tells it what to do, one small step at a time. This lesson draws the line between the machine and the instructions, and between the instructions and the data they work on.

Difficulty: Beginner · Know this first: F01 — A Computer You Can Point At

Run it as:

When it breaks, I check

One thing to remember

Where the time goes

The bar below is a worked example for this lesson, not a measurement. It shows shares of 100 instructions in a small program. The shape is the point: most instructions do the work itself. Switch the scenario and watch the checking step grow when one instruction is wrong.

Extra diagram · from scratch to master

Code and data: two different things in one box

Start with the machine alone. Add the instructions, then the data, and watch them stay separate.

6 boxes on the map1 list1 pile of stuff
The machine
waits
Instructions
the list
Data
the stuff
CPU reads
one at a time
Work happens
small changes
Answer
left behind
Request / flowResponse · the way backFailure / dead end

Extra diagram · from scratch to master

One bad instruction, and where it bites

Follow a program with one wrong step. The machine follows it faithfully, and the damage spreads forward.

6 steps in the story1 bad step0 warnings from the machine
Good list
starts right
Data in
numbers ready
CPU reads
step by step
Bad step
wrong change
Wrong value
spreads forward
Wrong answer
looks fine
Request / flowResponse · the way backFailure / dead end

Try it: change the inputs and watch it bend

Run a tiny program yourself. Type a number, and watch three instructions work on it, one at a time. The arithmetic is exact. The lesson is the order: each instruction takes the result of the one before it.

3

The program is three instructions long: (1) add 5, (2) double it, (3) show the answer. The data is your number. The instructions are fixed.

Try this: (1) Set the number to 3. Add 5 gives 8, double it gives 16. (2) Set it to 10. Add 5 gives 15, double it gives 30. (3) Set it to 0. The answer is 10, because 0 plus 5 is 5, and 5 doubled is 10.

Check yourself

Three questions. No score is saved anywhere — this is just you against the material.

Basic to master

I take the same idea four times here. First I tell code from data. Then I read a program like a list. Then I see how big programs stay organised. Last I run programs I did not write.

Basic — Code is the list, data is the stuff

Definition: Software is a list of instructions. Data is what the instructions work on. The CPU reads the list one step at a time and does what it says. Input goes in, work happens, output comes out. That is all a program is.

Types:

  • A calculator program: instructions that add, data that is two numbers.
  • A photo program: instructions that shrink, data that is a photo.
  • A game: instructions that move things, data that is the score and the positions.

Uses: I use this when someone asks what software is. I do not talk about code. I talk about a list of steps and the stuff the steps work on. That picture holds for every program.

Dimensions: One program, a short list, a small pile of data. What breaks first is a wrong instruction, and I notice it when the answer is wrong. It costs nothing to learn the difference between code and data. It costs real time when I mix them up. The trade is simple: a clear list is easy to read, and an easy list is easy to fix.

Intermediate — Reading a program like a list

Definition: At this level I read a program top to bottom and follow it like a recipe. I track what each instruction changes. I know where the data comes from and where the answer goes. I can point at the instruction that made the answer wrong.

Types:

  • Straight lists: do this, then this, then this.
  • Lists with a check: if this is true, do that, otherwise do something else.
  • Lists that repeat: do this for each item in the pile.

Uses: I use this to find bugs. I read the list, I run it in my head with real numbers, and I watch for the step where the value goes wrong.

Dimensions: A program of hundreds of instructions, a pile of data. What breaks is the step I did not trace, and I notice it when the answer is wrong but the program looks fine. It costs patience to trace a list by hand. The trade is that tracing finds the bug, and guessing does not.

Advanced — Big programs stay organised

Definition: At this level a program is millions of instructions, split into files and pieces. Each piece does one job. The pieces call each other. The list is still a list, but it is organised so a human can find the part that matters.

Types:

  • Files: one job per file, so I know where to look.
  • Functions: named pieces of the list I can reuse.
  • Libraries: lists other people wrote, that I borrow instead of rewriting.

Uses: I use this when a program gets too big to hold in my head. I split it, name the pieces, and make each piece do one job well.

Dimensions: Millions of instructions, many people writing them. What breaks is the piece nobody owns, and I notice it when a change in one place breaks something in another. It costs discipline to keep pieces separate. The trade is that organisation costs effort up front and saves far more effort later.

Versions matter more than names. Two machines can both run Python and still behave differently, because the versions differ. I check the version before I trust that a program will work. A program written for one version can break on another, and the error message will not say why.

$ python3 --version
Python 3.12.3
$ ls /usr/bin/python*
/usr/bin/python3
/usr/bin/python3.12

Every flag in the commands above, letter by letter.

  • python3 --version: --version prints the version and stops. It runs no code. I run it first when a script fails, because the version is the first thing that differs between two machines.
  • python3 -V is the same thing, shorter. Capital V. Lowercase v means something else, so I type the capital on purpose.
  • ls with no flags lists names, nothing else. No sizes, no dates. The * in /usr/bin/python* is a glob. The shell expands it to every matching name before ls ever runs.
  • One more flag worth knowing: ls -1 prints one name per line. When the output goes to a pipe it is already one per line. On screen, -1 forces it.

Check it: run python3 --version and python3 -V. Both print Python 3.12.3. Then run ls /usr/bin/python* and ls -1 /usr/bin/python*.

Try it: run python3 --version on two machines you use. If the numbers differ, that is a real difference. Write both numbers down. When something works on one machine and not the other, the version is the first thing I compare.

A file can change under you. Software is files, and files can be edited, replaced, or corrupted without anyone noticing. I check that a file is the one I expect by hashing it. A hash is a fingerprint. If the file changes by one byte, the fingerprint changes completely.

$ printf 'hello\n' > sumtest.txt
$ sha256sum sumtest.txt
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03  sumtest.txt

Every flag in the commands above, letter by letter.

  • printf takes no flags here. The first word in quotes is the format. \n is a newline. The > writes the output to a file instead of the screen. Without it, the text goes to the screen and no file is made.
  • sha256sum takes no flags here. It prints the hash, then the filename. One letter changed in the file gives a completely different hash. That is the whole point of the check.
  • One more flag worth knowing: sha256sum -c is check mode. Save the hashes to a file first, then run sha256sum -c sumtest.sha. It prints OK for each file that still matches.

Check it: run the two commands above, then run sha256sum sumtest.txt > sumtest.sha and sha256sum -c sumtest.sha. It prints sumtest.txt: OK. Change one letter in the file and run -c again. It prints FAILED.

Try it: hash a file, change one letter in it, and hash it again. The two hashes will look nothing alike. That is the point. A hash tells you the file changed. It does not tell you what changed.

Master — Running programs I did not write

Definition: At this level I run software other people wrote, on machines I do not own, for users I never meet. I cannot read every instruction. I trust the program by watching what it does: its inputs, its outputs, its errors, and its speed. I treat every program as a list I have not read, and I verify it by its behaviour.

Types:

  • Vendor software: lists I cannot read, so I test what they do.
  • Open source: lists I can read, but usually do not, so I test what they do.
  • Services: programs running on someone else’s machine, that I reach over the network.

Uses: I use this when I adopt a new tool. I do not read its source first. I run it, feed it real input, and check the output. Behaviour is the test.

Dimensions: Many programs, many machines, many users. What breaks is the program I trusted without testing, and I notice it when its output is wrong and nobody can say why. It costs time to test what I did not write. The trade is that testing costs hours, and blind trust costs incidents.

Verify what you download. A file you download is a file someone else wrote. Before I run it, I check its hash against the hash the maker published. If the two match, the file arrived intact. If they do not match, I do not run it. I download it again or I walk away.

$ printf 'hello\n' > sumtest.txt
$ sha256sum sumtest.txt
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03  sumtest.txt
$ printf 'hallo\n' > sumtest.txt
$ sha256sum sumtest.txt
622cb3371c1a08096eaac564fb59acccda1fcdbe13a9dd10b486e6463c8c2525  sumtest.txt

Try it: run the commands above. One letter changed, from e to a, and the whole hash changed. That is how you catch a download that was altered on the way to you. The check costs one command. Skipping it costs everything the program can touch.

Software you cannot see still runs. Most of the software on a machine never shows a window. It runs in the background, on a schedule, or when another program calls it. I list what is installed before I assume a machine is clean. A program I did not install is a question, not a fact.

$ ls /usr/bin | wc -l
$ ls /usr/bin/python*
/usr/bin/python3
/usr/bin/python3.12

Every flag in the commands above, letter by letter.

  • wc -l: -l counts lines. The | sends the output of ls into wc. Without the pipe, wc would wait for me to type.
  • Without -l, wc prints lines, words, and bytes all at once. The flag picks one number. I use it when I want a count, not a report.
  • Two ways to read what a command does: man ls opens the manual page for ls. ls --help prints a short summary and stops. --help is built into the command. man needs the manual pages installed. If your machine says man is not there, use --help instead.

Check it: run ls /usr/bin | wc -l, then ls /usr/bin | wc. The first prints one number. The second prints three. Then run ls --help and read the first lines.

Try it: run ls /usr/bin | wc -l. That is how many programs sit in one folder on your machine. Pick three names you do not recognise and read what each one does with man or --help. Knowing what is installed is the first step to knowing what is running.

Go deeper

Instructions and data both live in memory as numbers. The machine tells them apart only by the order it reads them. That is why a program that reads data as instructions breaks in strange ways. It follows numbers that were never meant to be followed.

A program is a list, but the list can jump. An instruction can say: go back to step 12. Or: if this is true, skip to step 30. Those jumps are how a short list does a big job. You will learn them properly in the next lessons.

The word software covers the list and everything around it: the files, the settings, the data the program needs to start. When I say a program, I usually mean the whole bundle, not just the list.

At 10x the size, the list does not change shape. It gets longer and it gets split into pieces. The CPU still reads one instruction at a time. The work still moves one small change at a time.

At 100x, the list is written by hundreds of people and runs on thousands of machines. The idea is the same. The organisation is the whole job.

ADD 5
DOUBLE IT
SHOW THE ANSWER

That is the whole simulator program, written as three lines. Read it top to bottom. That is what a program is.

Try it: the one-letter test. Create a file with one line, hash it, change a single letter, and hash it again. The two hashes share nothing. That is why a hash is a good check and a bad summary. It answers one question, did this file change, and it answers it with total certainty.

$ printf 'hello\n' > sumtest.txt
$ sha256sum sumtest.txt
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03  sumtest.txt
$ printf 'hallo\n' > sumtest.txt
$ sha256sum sumtest.txt
622cb3371c1a08096eaac564fb59acccda1fcdbe13a9dd10b486e6463c8c2525  sumtest.txt

One time it broke

What broke

A small program added two numbers and printed the answer. It printed the wrong answer, every time, and never showed an error. The numbers going in were right. The list was wrong: one instruction added 5 where it should have added 50. The machine followed it exactly.

Timeline

  • 10:02,the program printed 55. The right answer was 100.
  • 10:04,I checked the input numbers. They were right.
  • 10:06,I read the list out loud, one instruction at a time, with the real numbers.
  • 10:08,I found it. The third instruction added 5 instead of 50.
  • 10:09,I fixed the one instruction and ran it again. The answer was 100.

What changed after

Two things. First, I read the list with real numbers before I blame the machine. Second, I check the answer by hand when a program is new. A program that runs clean and gives a wrong answer is the hardest kind of bug to notice, because nothing looks broken.

If you remember nothing else

Design exercise

Write, in plain words, the list of instructions for a program that takes a list of prices and finds the most expensive one. No code. Just the steps, in order, as if you were telling a very literal friend what to do.

Clarifying questions to ask

  • What is the input, and what is the output?
  • What do you do before you look at the first price?
  • How do you decide whether a price beats the one you have so far?
  • What happens when the list of prices is empty?
  • Where would a wrong instruction hide in your list, and what wrong answer would it give?

Rough sizing

Start with the list. One instruction per line, about ten lines. The work is small: look at each price once, keep the biggest, show it at the end. For 100 prices that is 100 looks and 100 comparisons, which a CPU finishes before you blink. For 10 million prices it is still one look each, and the time grows with the list, not with anything else.

Trade-offs to name

A short list is easy to read and easy to get wrong in a small way. A longer list with checks is harder to read and catches mistakes. Checking the empty list costs one instruction and saves a crash. The trade is that every check costs a line, and it buys an answer you can trust.

Next in this series
Lesson F03 — Programming: Writing the Instructions