How to use comments in Perl code

The program code is executed by a computer. But I write this code and complement people. The computer is still as complex and intricate code — it just will perform. But if the code easy to understand to man, it will be easier and faster to complete and it will fewer mistakes.

Comments in the program is text intended for human use. The computer does not use comments. The objective of the review to make the code clearer for human. Comments all the time in the program code, when a person needs to change the code snippet, it reads the review and is he simplifies the understanding of what is happening in the code.

The second objective of the review is a tool when developing code. Often write code there is a piece which is not necessary, but very soon you will need. In this case, the fragment it is convenient to comment out code until run-debug code next. When work ends these commented out pieces of code should not stay.

Single-line comments

To write a comment in the Perl programming language you need to put the pound #. Everything after this symbol to the end of the line will be a comment.

The symbol array can be at the beginning of the line:

# This is a comment
my @arr = (1..10);

Or in front of the grille can be gaps:

foreach my $el (@arr) {
    # One more comment
    warn $el;
}

And review can go after the code:

my @arr = (1, 2, 3); # some description for @arr
my %h; # explanation of %h

Review can to write immediately after the pound symbol, but for readability you should put a space after #

#comment without a space
# comment with a space

If the hash is inside the string, it is not a review, as part of a string:

my $str = 'Line 1
# This is not a comment, but part of a string variable
Line 2';

Configuring the editor

When there is an active work on the project there is a need to comment out several lines of code.

It is very convenient to configure the text editor to be as easy as possible. For example to make the editor work like this:

  • highlight all the lines you want to comment out
  • click Ctrl+/
  • the result is in front of all the lines which were selected symbol appears #

Multi-line comments

In the code the Perl program can be written documentation. It uses a special markup language POD (it stands for Plain Old Documentation). POD specifically designed to to write the text for humans in the program code.

Here's an example POD markup to the documentation about the method:

=head2 get_name

    my $name = $obj->get_name();

Returns the name of the Person stored in the object.

The return value is a scalar with length >= 1 and <= 100.

=cut

sub get_name {
    my ($self, @other) = @_;

    die 'get_name should not get any parameters' if @other;

    return $self->{_name};
}

POD markup always starts with equal =, after which no space is Directive. For example =head2 or =item. Symbol = must always be at the beginning of the row. If he will spaces, it will not work.

POD the markup always ends with a Directive =cut. And before the character = also should not be gaps.

Use multiline comments for temporarily removing code

If you work on a project you will need to temporarily comment out a piece of code for this you could use this technique. Before the code you want to comment you need to write =a, and after the code =cut:

my $str = 'AB';

=a
foreach my $el (1..10) {
    parse_index($el);
}
=cut

All that is written between =a and =cut will be hidden from the Perl interpreter.

But it is a decision that cannot be left in the program code. =a is not a valid POD Directive and different POD parsers will give errors when working with code which contains such incorrect POD.

Other articles

Comments