08. Comments and notes to yourself

You met comments briefly in Chapter 07: text Lua ignores when it runs the file. They let you leave notes for the most forgetful programmer you will ever work with — yourself, next week. Good comments turn a wall of code back into something you can read.

The two kinds of comment

A single-line comment starts with two dashes --. Everything from there to the end of the line is ignored:

-- This whole line is a note for a human.
print("Hi")          -- A note can also sit after some code.

A multi-line comment starts with --[[ and ends with ]]. Lua ignores everything between them, over as many lines as you want:

--[[
  This is a longer note. It can run for several lines.
  Lua ignores all of it until the closing marker.
]]
print("Still runs.")

Use single-line comments for short notes, multi-line ones for a paragraph at the top of a file or any longer explanation.

Open exercises/08/01-comment-styles.lua. It has three print calls. Add a single-line comment above the first, an end-of-line comment after the second, and a multi-line comment at the top explaining the file. Run it — the output should not change.

Comment why, not what

The most common beginner mistake is comments that just repeat the code:

local score = 0     -- set score to 0
score = score + 10  -- add 10 to score

Those comments add nothing — the code already says what it does. A useful comment explains why, or warns about something surprising:

local score = 0       -- players always start a round on zero
score = score + 10    -- bonus for finishing under par

A good rule: if the comment and the code say the same thing, delete the comment. Save them for the why, the gotcha, and the not obvious.

Commenting out code

Comments have a second job: switching code off without deleting it — one of the most useful debugging tricks around.

Suppose a program misbehaves and you suspect one line. Put -- in front of it and run again:

print("Step 1")
-- print("Step 2")
print("Step 3")

Now "Step 2" never prints. If the problem goes away, you found your culprit. To switch the line back on, delete the -- — faster and safer than deleting and retyping it later.

To switch off a whole block, wrap it in --[[ and ]]:

--[[
print("These three")
print("lines are")
print("all switched off")
]]
print("Only this line runs.")

Do not put the closing ]] inside a multi-line comment's text. The first ]] Lua sees ends the comment, and whatever follows is treated as code again — usually an error. Keep ]] on its own line at the end.

A header for every file

A habit worth building: start each file with a short multi-line comment saying what it is for. Future-you will thank present-you.

--[[
  Greeting program.
  Asks for nothing; just prints a friendly welcome banner.
  Written while learning Chapter 08.
]]

print("Welcome!")

Homework

Homework files are in exercises/08/homework/.

Problem 1 — Annotate a program

Open exercises/08/homework/01-annotate.lua. It has a few lines of working code with no comments. Add a multi-line header saying what the file does, plus at least two single-line comments explaining why a line is there (not what it does). The output must not change.

Problem 2 — Find the bug by commenting out

Open exercises/08/homework/02-comment-out.lua. One of its print lines produces output that should not be there. Comment out exactly one line so the program prints only:

start
end

Do it by adding --, not by deleting the line.

Problem 3 — Switch off a block

Open exercises/08/homework/03-block-off.lua. Using a single --[[ ]] multi-line comment, switch off the three middle print lines so only the first and last lines print. Run it to confirm.

Challenge — Why, not what

Open exercises/08/homework/04-why-not-what.lua. It is full of useless comments that just repeat the code. Rewrite each so it explains why the line exists, or delete it if nothing useful can be said. Aim for fewer, better comments.

Stuck or finished? Open the homework solutions page.