What are the common workarounds for multi-line comments in Perl?

Question

This RFC mentions

Unlike many programming languages Perl does not currently implement true multiline comments. This, and the workarounds that are in common use can be problematic. This could be solved by adding a new syntax to allow for comments to span more than one line, like the variation on here-documentation cited below.

What are the common workarounds?

Two techniques I found here are

if (0) {
  <comment>
}

and

=pod
<comment>
=cut

Are these safe to use? Are there others that work better?

Answer 1

An editor with a "Comment Region" function.

For example, Komodo Edit. I'm pretty sure Eclipse and JEdit do it as well, but I don't have them handy to check.

The feature usually inserts a "Comment this line" symbol at the start of every line in the selected region. It has the benefit of not conflicting with existing comments (which is a risk if you wrap an area containing a multi-line comment in most languages)

Answer 2

The downside of the "if" solution is that the commented out code still has to be compiled (and therefore still has to be syntax checked).

The downside of your pod solution is that your comments will appear in any documentation generated from the pod.

I use a version of the pod solution that doesn't have that problem. Pod supports =begin format ... =end format paragraphs that are handled by specific formatters. I just invent a "comment" format that isn't handled by any of the formatters I use.

=begin comment

This is ignored by everything

=end comment

Update:

I missed an important part of my example. You need to end the pod section with =cut. Here's a full example.

#!/usr/bin/perl

print "This line is executed\n";

=begin comment

print "This line isn't\n";

=end comment

=cut

print "This line is\n";

Answer 3

My favorite multi-line comment device is __END__.

print "Hello world\n";

__END__

The script has ended. Perl does not treat this part of the file as code.

I can put whatever I want down here. Very handy.

Answer 4

Although it's non-standard, I just use

=ignore 

sub blah { ... }
my $commented_out_var = 3.14;

=cut

It works just as well, and reminds me that it is not POD.

• Aside: It is an interesting thing that POD gives us a flexible framework for including various regions that should not regarded as code, specifying what that region means. Clearly we "comment things out" because comments work this way. Yet, it is clear from the term that comments are meant to be words, not instructions; documentation not alterations.

Answer 5

One special use-case is commenting out several lines of code. But if you use a version control system, you can just delete unwanted code rather than commenting it out, and if you ever need it back, just fetch the old revision.

Answer 6

The Perl documentation tells you how to do it in perlfaq7]. It's plenty safe, and since we can do it with Pod, we don't need additional syntax to do it:

---

How can I comment out a large block of perl code?

You can use embedded POD to discard it. Enclose the blocks you want to comment out in POD markers. The <=begin> directive marks a section for a specific formatter. Use the "comment" format, which no formatter should claim to understand (by policy). Mark the end of the block with <=end>.

   # program is here

   =begin comment

   all of this stuff

   here will be ignored
   by everyone

   =end comment

   =cut

   # program continues

The pod directives cannot go just anywhere. You must put a pod directive where the parser is expecting a new statement, not just in the middle of an expression or some other arbitrary grammar production.

See perlpod for more details.

Answer 7

In addition to the

=begin comment

multi-paragraph comments here

=end comment

=cut

form in other answers, you can also do this:

=for comment
this is a single pod paragraph comment do
not put extra blank lines after =for.  the
comment ends after the first blank line and
regular pod continues until =cut

Hello! C<Yay!>

=cut

the comment paragraph will not appear in the pod output, but the Hello "Yay!" will.