Как использовать комментарии в Perl коде

Код программы выполняется компьютером. Но пишут и дополняют этот код люди. Компьютеру все равно насколько сложный и запутанный код — он просто его выполнит. Но если код легко понять человеку, то его будет проще и быстрее дополнить и в нем будет меньше ошибок.

Комментарии в программе — это текст предназначенный для человека. Компьютер никак не использует комментарии. Задача комментариев сделать код понятнее для человека. Комментарии все время находятся в коде программы, когда человеку нужно изменить фрагмент кода, он читает комментарий и это упрощает ему понимание что происходит в коде.

Вторая задача комментариев — это инструмент при разработке кода. Часто бывает — пишешь код, есть кусок который сейчас не нужен, но очень скоро понадобится. В этом случае этот фрагмент кода удобно закомментировать, пока запускаешь-отлаживаешь код рядом. Когда работа заканчивается таких закомментированных кусков кода остаться не должно.

Однострочные комментарии

Чтобы написать комментарий в языке программирования Perl нужно поставить символ решетки #. Все после этого символа и до конца строки будет являться комментарием.

Символ решетка может быть в самом начале строки:

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

Или перед решеткой могут быть пробелы:

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

А также комментарий может идти после кода:

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

Комментарий можно писать сразу после символа решетки, но для удобства чтения стоит поставить пробел после #

#comment without a space
# comment with a space

Если символ решетки находится внутри строки, то это не комментарий, а часть строки:

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

Настройка редактора

Когда идет активная работа над проектом бывает необходимость закомментировать сразу несколько строк кода.

Очень удобно настроить текстовый редактор чтобы это можно было делать как можно проще. Например можно сделать чтобы редактор работал вот так:

  • выделяешь все строки, которые нужно закомментировать
  • нажимаешь Ctrl+/
  • результат — перед всеми строчками которые были выделены появляется символ #

Многострочные комментарии

В коде Perl программы можно писать документацию. Для этого используется специальный язык разметки POD (это расшифровывается как Plain Old Documentation). POD специально предназначен для того чтобы писать текст для человека в коде программы.

Вот пример POD разметки с документацией про метод:

=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 разметка всегда начинается с символа равно =, после которого сразу без пробела идет директива. Например =head2 или =item. Символ = всегда должен быть в самом начале строки. Если перед ним будут пробелы, то это работать не будет.

POD разметка всегда заканчивается директивой =cut. И перед символом = тоже не должно быть пробелов.

Использование многострочных комментариев для временного убирания кода

Если при работе над проектом вам нужно временно закомментировать какой-то кусок кода, то для этого можно использовать вот такой прием. Перед кодом который нужно закомментировать нужно написать =a, а после кода =cut:

my $str = 'AB';

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

Все что написано между =a и =cut будет спрятано от Perl интерпретатора.

Но это решение которое нельзя оставлять в коде программы. =a не является валидной POD директивой и разные парсеры POD будут выдавать ошибки при работе с кодом в котором содержится такой некорректный POD.

Другие статьи

Комментарии