4.4 Comments

4.4 Comments

Comments are to your program as the Three Bears' furniture was to Goldilocks; too few aren't good enough, and more are not better. Ideally, code should not need commenting; for example, instead of saying:

# If employee was hired more than a week ago:

# get today's week number, convert the employee's

# hire date using the same format, take difference.

use POSIX qw(strftime);

use Date::Parse;

chomp(my $t1 = 'date +%U');

my @t2 = strptime($employee->hired);

if (strftime("%U", @t2) - $t1 > 1)

say:

if (time - $employee->hired > $ONE_WEEK)

by storing times in UNIX seconds-since-epoch format and defining $ONE_WEEK earlier as 60 * 60 * 24 * 7. This is not only easier to read but lacks the bug in the previous code. That tortured tangle of pendulous programming may look absurd, but I have often seen worse. A developer is used to getting a date from the date command in shell scripts, does the same in a Perl program, stores the result in the same format, and it goes downhill from there.

Sometimes you can't make the code clear enough. When you add a comment the word to keep in mind is, Why? Don't just recapitulate what the code does, but say why you're doing it. This doesn't need to be a verbose justification, but can be as simple as this:

if (time - $employee->hired > $ONE_WEEK)  # Past probation?

Although then you have to ask why it wasn't written as:

if (time - $employee->hired > $PROBATION_PERIOD)

So a better example would be something like:

if (my ($name) = />(.*?)</s)   # /s: fields can contain newlines

which indicates some hard-won piece of knowledge.

4.4.1 Sentinel Comments

Sometimes you need to put a reminder in your code to change something later. Perhaps you're in the middle of fixing one bug when you discover another. By putting a distinctive marker in a comment, you have something you can search for later. I use the string "XXX" because gvim highlights it especially for this purpose.^[5] (I suppose it also makes the program fail to pass through naive adult content filters.)

^[5] Even though I use Emacs most of the time; it helps to hedge your bets in the perennial "Favorite Editor War."

4.4.2 Block Comments

People often ask how they can comment out a large piece of code. Wrapping it in an if (0) {...} block prevents it from being run, but still requires that it be syntactically correct.

Instead, wrap the code in Plain Old Documentation (POD) directives so it's treated as documentation.^[6] There are a number of ways of doing this; here I've used =begin:

^[6] See Section 10.3.1.

=begin comment



# Here goes the code we want

# to be ignored by perl



=end comment



=cut

This will still be interpreted as POD, though. However, in this case, POD formatters should ignore the block because none of them know what a block labeled "comment" is. I needed the =end directive to keep the POD valid (=begin directives should be matched), and I needed the =cut directive to end POD processing so perl could resume compiling the following code. Remember that POD directives need blank lines following them because they are paragraph-based. I'll go into what POD can do for your program in more detail in Chapter 10. For a more creative solution to the multiline comment problem, see http://www.perl.com/pub/a/2002/08/13/comment.html.