Bessarabov's Perl Style Guide

Эпиграф — "Tim Toady Bicarbonate".

Perl можно использовать множеством разных способов, но удобно, когда есть какие-то общие правила. В этом посте я собираю мои предпочтения о том как нужно писать Perl код. Это в первую очередь документ для меня, но я буду очень рад, если другие люди тоже станут использовать этот Style Guide без изменений, либо возьмут этот докумен за базу и внесут необходимые правки (т.е. напишут, что используется BPSG версии 2.0.0, но правило 34 затирают своим правилом).

Любое правило можно нарушить, но нужно веская причина почему правило стоит игнорировать в этом конкретном случае.

Версия документа: 2.0.0 (используется семантическое версионирование)

Changelog:

1.0.0   2013-08-08
        [Major]
        * Inital version

2.0.0   2014-01-19
        [Major]
        * Simplified the numeration scheme

2.1.0   2014-02-04
        [Minor]
        + 6. Не должно быть закомментированного кода

2.2.0   2014-08-05
        [Minor]
        + 7. Всегда использовать прагмы strict и warnings

1. Кодировка файлов UTF-8

Это самая популярная кодировка, конечно стоит использовать именно ее.

Нужно найти/написать Perl тест, чтобы иметь возможность проверять что файл написан в кодировке UTF-8.

2. В файлах не должен использоваться BOM

BOM — это Byte order mark, штука с помощью которого указывают кодировку файла. Поскольку уже есть правило 1.1, которое говорит что кодировка всегда UTF-8, то BOM использовать избытачно.

Нужно найти/написать Perl тест, который может проверять что BOM не используется.

3. POD всегда начинается с =encoding UTF-8

Далеко не всегда в POD есть какие-то символы, которых нет в простой 8-и битной кодировке Latin1. Когда такие символы есть, то конечно, обязательно нужно узазывать =encoding UTF-8. Но даже когда весь POD написан простым latin1, все равно стоит указывать кодирову UTF-8, чтобы изменение текста не потребовало еще и дописывание директивы.

Ссылка на stackoverflow, с ответом что из всех возможных кодировок "utf8", "UTF-8", "utf-8" нужно писать именно "UTF-8".

И директива =encoding UTF-8 всегда должна быть самой первой директирой POD.

4. Для имен переменных используется нижний регистри и символ "_"

Нужно писать $some_variable, а не $SomeVariable или как-то иначе.

Предпосылки этого — то что это самый читаемый стандарт и это очень распространенная практика в мире Perl.

5. Переменная с именем файла называется $file_name

Достаточно часто в коде встречаются переменные которые хранят в себе имя какого-то файла. Такую переменую называют по разному: иногда $filename, а иногда $file_name. Какого-то очивидного плюса нет ни у одного варианта, но чтобы был какой-то стандарт, я выбрал вариант $file_name, так как на мой взгляд это красивее.

Википедия тоже не вносит однозначного ответа как правильно, цитирую:

A filename (also written as two words, file name) ...

6. Не должно быть закомментированного кода

Исходный код должно быть просто читать. Если в коде есть закомментированные строки, то возникает вопрос почему эти строки не используются, — не ошибка ли это. Чтобы убрать такие вопросы в исходном коде не должно быть закомментированных строк кода.

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

Неправильно:

$model->do_work();
# Uncomment to outut debug:
#
# say "Model after do_work()";
# say "Model status: " . $model->status;
# say "Model output: " . $model->output;

Правильно:

$model->do_work();

7. Всегда использовать прагмы strict и warnings

Во всех скриптах и модулях дожено быть:

use strict;
use warnings FATAL => 'all';

Пример проблемы которая может возникнуть если не использовать в посте "Грабля Perl кода my $success = false;"