Comments and Readable Perl

Part I · Module 1 · Chapter 1.9 · Comments and Readable Perl

1. The Mechanism

A # means "ignore the rest of this line". That is the whole rule:

use strict;
use warnings;

# The tool writes ERROR and never FATAL, so only ERROR is counted.
print "counting ERROR only\n";   # end-of-line note

#print "this line is disabled\n";

counting ERROR only

Three forms, all visible above:

• A full-line comment, used to explain what follows.
• An end-of-line comment, used to annotate the line it sits on.
• Commented-out code — a # placed in front of a real statement so it does not run.

There is no multi-line comment form in Perl of the kind /* ... */ provides elsewhere. To disable a block of lines you put a # on each one, which every editor will do for you.

2. The One Place # Is Not a Comment

Inside a quoted string, # is an ordinary character:

perl -e 'print "a # inside quotes stays\n"'

a # inside quotes stays

That is the behaviour you want — otherwise you could never print a # — and it is worth seeing once so that you do not mistrust it later. The same is true in patterns, where # appears frequently and means nothing special.

There is a second exception you have already met: the shebang from Chapter 1.4. #!/usr/bin/env perl is a comment as far as Perl is concerned, and an instruction as far as the operating system is concerned. It is the only line in a Perl file that is read by something other than Perl and a human.

3. What to Write

The mechanism took two sections. This is the part that matters.

A comment that restates the code is worse than no comment, because it has to be maintained and tells the reader nothing:

# print the marker
print "ERROR\n";

A comment that records a decision or a constraint is worth keeping, because that information exists nowhere else in the file:

# This tool reports failures as ERROR and never as FATAL, so searching for
# FATAL here would always find nothing. Confirmed against tool output, not
# assumed from the documentation.
print "counting ERROR only\n";

The useful test is: would the next reader otherwise have to guess, experiment, or ask someone? If yes, write it down. If the code already says it plainly, do not.

Three categories are worth the keystrokes nearly always:

• Why, not what. The code shows what happens. Only you know why that was the right choice.
• Facts about the outside world. The format a tool emits, the field that is absent on older versions, the reason a value is 3 and not 5. These are assumptions, and an assumption that is not written down is indistinguishable from a mistake.
• What you tried and rejected. "The obvious approach fails because…" saves the next person from repeating your afternoon.

4. Why This Matters More in Perl Than in Most Languages

This is not a general plea for commenting. Perl has two specific properties that make it unusually dependent on them.

A correct line can be unreadable. A pattern such as /^\s*(\S+)\s+(-?\d+\.\d+)/ is precise, unambiguous and almost impossible to read aloud. It does not say what it is for. Module 11 teaches you to write these; the comment above one is where its purpose lives. Perl even has a mode, covered in Chapter 11.17, whose entire function is to let you put comments inside a pattern.

Punctuation carries meaning. Variables with names like $! and $@ — introduced in Chapter 2.12 — are real and common, and the difference between two of them can change what a script reports. A reader who has not memorised them has no way to tell from the line itself.

Add the fact that Perl automation tends to be long-lived and infrequently touched, and the comment stops being politeness and becomes the only surviving record of intent.

5. Comments Are Not Documentation

One boundary worth drawing now. Comments are notes to someone reading the source. Perl also has a documentation format, POD, which travels with the file and can be read as a manual page rather than by opening the code. That is the subject of Chapter 1.14 — where you will read Perl's own documentation, which is written exactly that way.

The practical division: a comment explains a line to someone editing it; documentation explains the script to someone using it. A script that others run deserves both.

6. Mistakes and How They Look

A comment that has drifted. The code changed and the comment did not, so the file now contains a confident false statement. This is the main argument against commenting what — a restatement goes stale, a reason rarely does. When you change a line, read the comment above it.

Commented-out code left behind. A disabled statement with no note explaining why is a question nobody can answer. Either say why it is there or delete it; version control already remembers it.

Expecting # to work inside a string. As §2 showed, it does not comment there — which is almost always what you want, but surprises people once.

Assuming a # block comment exists. There is no /* ... */ in Perl. Each line needs its own #.

7. What You Should Be Able to Say Now

1. # makes Perl ignore the rest of the line; there is no multi-line comment form.
2. Inside a quoted string, # is an ordinary character.
3. The shebang is a comment to Perl and an instruction to the operating system.
4. A comment restating the code is a liability; a comment recording a reason or an external fact is an asset.
5. Perl's patterns and punctuation variables make comments more load-bearing here than in most languages.
6. Comments and documentation are different jobs — the second is POD, covered in Chapter 1.14.

8. Exercise

Exercise 1 — all three forms. Write a short script using a full-line comment, an end-of-line comment, and one commented-out print. Run it and confirm only the live statements produce output.

Exercise 2 — improve a comment. Rewrite this so the comment is worth keeping: # add one to the count above a line that increments a counter. You may invent a plausible reason; the point is to write a why.

Exercise 3 — the string exception. Write a single print that outputs the text use # to comment and confirm the # survives. Explain in one sentence why Perl does not treat it as a comment.

Exercise 4 — judgement. You inherit a script with a commented-out block of five lines and no explanation. List the two things you would do, in order, and say which one you would do if you could only do one.

9. Summary

• # ignores the rest of the line. Full-line, end-of-line, and commenting-out are the three uses; there is no block form.
• Inside quotes, # is just a character — and the shebang is the one comment read by the operating system.
• Write why, not what. A restatement goes stale and tells the reader nothing they could not see.
• Record external facts and rejected approaches — those exist nowhere else in the file.
• Perl needs this more than most languages, because patterns and punctuation variables cannot explain themselves.
• Comments are not documentation; POD and perldoc are a separate job, covered in Chapter 1.14.

The remaining chapters of this module are about making Perl itself help you. Chapter 1.10 starts with the pragma that turns an entire class of silent mistake into a refusal to run.