05. Naming and decomposition

The last paper chapter. It covers two habits that separate painful code from code that almost reads itself: good names, and breaking a big job into small steps. Neither needs a computer, and both make the rest of the book easier to write and fix.

Names are messages to the next reader

The computer does not care what you call things. x, q7, and monsters_left all work the same. Names are for the next person to read the code — usually you, a week later, having forgotten everything.

Read these two programs. They do exactly the same thing.

local x = 60
local y = 8
local z = x * y
print(z)
local minutes_per_hour = 60
local hours = 8
local total_minutes = minutes_per_hour * hours
print(total_minutes)

Both print 480, but only the second tells you what 480 means. The first makes you a detective; the second, a reader. The extra typing pays for itself the first time you come back and understand it instantly.

What makes a good name

  • Say what it holds, not what type it is. player_name beats string1; coins_left beats number_thing.
  • Longer is fine if it is clearer. seconds_until_respawn is a great name. Nobody ever cursed code for being too readable.
  • Match the size of the job. A counter that lives two lines can be i. A value that travels the whole program deserves a real name.
  • Be consistent. If one score is player_score, do not call the next enemyScore. Pick a style and stick to it in a file.

You do not need the Lua rules about names yet — those come in the variables chapter. For now, build the habit: before you write a name, ask would a stranger know what this holds?

Decomposition: big job into small steps

A whole program at once is scary. A list of small steps is not. Chopping a big task into small, separately-understandable pieces is called decomposition, and it is how every real program gets built.

You did this in Chapter 02 without the fancy word: a flowchart is a big task broken into one-box steps. Here it is in plain writing. Suppose the job is "greet a player and show their stats":

  1. Ask the player for their name.
  2. Ask the player for their level.
  3. Work out a title from the level (e.g. "Novice" or "Hero").
  4. Print a greeting line.
  5. Print a stats line.

Each step is small enough to picture completely. None of them is "the whole program", the scary thing you started with. Later, several of these steps will each become a short function with its own name — and a well-named step is already halfway to a well-named function.

Naming the steps

Good decomposition and good naming are the same skill pointed at different things. Naming a step is really naming a future function. Compare:

  • Vague step: "do the stuff with the numbers".
  • Named step: "work out the total score" → later, total_score().

If you cannot name a step in a short phrase, it is probably two steps in a trench coat. Split it until each step has a clear, short name.

Think of a small game you like. On paper, write one sentence describing the whole thing it does. Then break that sentence into three to six named steps. Notice how each step is easy to think about, even when the whole was not.

How small is small enough?

A step is small enough when you can hold all of it in your head and name it clearly. If it still feels foggy, break it again. Once you reach "add 1 to the score", stop — you have gone far enough. The goal is steps you can trust, not the most steps possible.

Homework

The last paper homework in the book. After this, you install Lua and write real code.

Problem 1 — Rename the mystery

Here is a program with deliberately useless names. You cannot run it, but you can read it. On paper, rewrite the four names so a stranger would understand what each holds. (Hint: the maths is a shopping total.)

local a = 3
local b = 250
local c = a * b
local d = c + 100
print(d)

Write the four new names and one sentence saying what the program works out.

Problem 2 — Chop the chore

Pick one big job: get ready for school, bake a cake, or set up a board game for four players. Break it into five to eight small steps, each a short named phrase (like "pour the batter", not "do the middle bit"). Number them in order.

Problem 3 — Name the steps as functions

Take your steps from Problem 2. For any three of them, write the short function-style name you would give that step, in the shape word_word (for example, "pour the batter" → pour_batter). You are not writing code — just practising turning a step into a name.

Challenge — Two-level breakdown

Take the job run a small birthday party. Break it into four big steps (before, food, games, after, or your own). Then pick one and break it into three smaller steps. You have now done decomposition twice — a big job into parts, one part into smaller parts. Mark clearly which steps belong under which. This nesting is how large programs are organised.

Stuck or finished? Open the homework solutions page.