perlstyle

СОДЕРЖАНИЕ

• ИМЯ
• ОПИСАНИЕ

ИМЯ

perlstyle - Руководство по стилю Perl

ОПИСАНИЕ

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

Самое важное – использовать strict и warnings во всех ваших программах или знать причину, по которой этого не следует делать. Вы можете отключить их явно для определенных частей кода с помощью no warnings или no strict, и это может быть ограничено конкретными предупреждениями или функциями strict, которые вы хотите отключить. Флаг -w и переменная $^W не должны использоваться для этой цели, поскольку они могут повлиять на код, который вы используете, но не написали, такой как модули из ядра или CPAN.

Лаконичный способ добиться этого – использовать синтаксис use VERSION, запросив версию 5.36 или выше, что включит как strict, так и warnings прагмы (а также несколько других полезных названных функций).

use v5.36;

Что касается эстетики расположения кода, единственное, что Лэрри очень заботит, это то, чтобы закрывающая фигурная скобка многострочного блока выравнивалась с ключевым словом, с которого начинается конструкция. Помимо этого, у него есть другие предпочтения, которые не так важны:

• Отступ в 4 столбца.

• Открывающая фигурная скобка на той же строке, что и ключевое слово, если это возможно, в противном случае выровненная.

• Пробел перед открывающей фигурной скобкой многострочного блока.

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

• Пробела перед точкой с запятой нет.

• Точка с запятой опущена в «коротком» однострочном блоке.

• Пробелы вокруг большинства операторов.

• Пробел вокруг «сложного» индекса (в скобках).

• Пустые строки между частями, выполняющими разные действия.

• Неувязанные else.

• Пробела между именем функции и открывающей скобкой нет.

• Пробел после каждой запятой.

• Длинные строки разделяются после оператора (кроме and и or).

• Пробел после последней скобки, соответствующей текущей строке.

• Выравнивание соответствующих элементов по вертикали.

• Опускание избыточных знаков препинания, если это не повлияет на ясность.

У Лэрри есть причины для каждого из этих пунктов, но он не утверждает, что все остальные думают так же, как он.

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

• Просто потому, что вы МОЖЕТЕ что-то сделать определенным образом, не означает, что вы ДОЛЖНЫ это делать. Perl разработан так, чтобы давать вам несколько способов сделать что-то, поэтому подумайте о том, чтобы выбрать наиболее читаемый. Например

  open(my $fh, '<', $foo) || die "Can't open $foo: $!";

  лучше, чем

  die "Can't open $foo: $!" unless open(my $fh, '<', $foo);

  потому что второй способ скрывает основную мысль утверждения в модификаторе. С другой стороны

  print "Starting analysis\n" if $verbose;

  лучше, чем

  $verbose && print "Starting analysis\n";

  потому что основная мысль не в том, ввёл ли пользователь -v или нет.

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

  В том же духе, просто потому, что вы МОЖЕТЕ опустить скобки во многих местах, не значит, что вы должны это делать:

  return print reverse sort num values %array;
  return print(reverse(sort num (values(%array))));

  В случае сомнений, используйте скобки. По крайней мере, это позволит кому-то нажать на клавишу % в vi.

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

• Не придумывайте глупые ухищрения для выхода из цикла в начале или в конце, когда Perl предоставляет оператор last, чтобы вы могли выйти посередине. Просто «отступите» его немного, чтобы сделать его более заметным:

  LINE:
      for (;;) {
          statements;
        last LINE if $foo;
          next LINE if /^#/;
          statements;
      }

• Не бойтесь использовать метки циклов — они служат для повышения читаемости, а также для выхода из циклов на нескольких уровнях. См. предыдущий пример.

• Избегайте использования grep() (или map()) или обратных кавычек в контексте void, то есть когда вы просто выбрасываете их возвращаемые значения. У этих функций есть возвращаемые значения, поэтому используйте их. В противном случае используйте цикл foreach() или функцию system() вместо этого.

• Для переносимости, когда вы используете функции, которые могут не быть реализованы на каждой машине, протестируйте конструкцию в eval, чтобы увидеть, не произойдёт ли ошибка. Если вы знаете, в какой версии или патче была реализована конкретная функция, вы можете проверить $] ($PERL_VERSION в English) для проверки, будет ли она доступна. Модуль Config также позволит вам изучить значения, определённые программой Configure при установке Perl.

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

• Хотя короткие идентификаторы, такие как $gotit, вероятно, в порядке, используйте подчёркивания для разделения слов в более длинных идентификаторах. Обычно легче читать $var_names_like_this, чем $VarNamesLikeThis, особенно для носителей языка, не являющихся носителями английского языка. Это также простое правило, которое последовательно работает с VAR_NAMES_LIKE_THIS.

  Имена пакетов иногда являются исключением из этого правила. Perl неофициально резервирует имена модулей в нижнем регистре для модулей «pragma», таких как integer и strict. Другие модули должны начинаться с заглавной буквы и использовать смешанный регистр, но, вероятно, без подчёркиваний из-за ограничений в представлении имён модулей как файлов на примитивных файловых системах, которые должны уместиться в нескольких разрядах.

• Вы можете найти полезным использование регистра букв для указания области или природы переменной. Например:

  $ALL_CAPS_HERE   constants only (beware clashes with perl vars!)
  $Some_Caps_Here  package-wide global/static
  $no_caps_here    function scope my() or local() variables

  Имена функций и методов, похоже, лучше всего работают в нижнем регистре. Например, $obj->as_string().

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

• Если у вас есть действительно сложная регулярная выражение, используйте модификаторы /x или /xx и добавьте пробелы, чтобы сделать её немного менее похожей на шум в строке. Не используйте косую черту в качестве разделителя, когда в вашей регулярке есть косые черты или обратные косые черты.

• Используйте новые операторы and и or для того, чтобы не приходилось так много использовать скобки для операторов списков и уменьшить количество знаков препинания-операторов, таких как && и ||. Вызывайте свои подпрограммы так, как будто это функции или операторы списков, чтобы избежать избыточных амперсандов и скобок.

• Используйте здесь документы вместо повторяющихся print() заявлений.

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

  $IDX = $ST_MTIME;
  $IDX = $ST_ATIME       if $opt_u;
  $IDX = $ST_CTIME       if $opt_c;
  $IDX = $ST_SIZE        if $opt_s;
  
  mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
  chdir($tmpdir)      or die "can't chdir $tmpdir: $!";
  mkdir 'tmp',   0777 or die "can't mkdir $tmpdir/tmp: $!";

• Всегда проверяйте возвращаемые коды системных вызовов. Хорошие сообщения об ошибках должны отправляться в STDERR, включать, какая программа вызвала проблему, какие системные вызовы и аргументы потерпели неудачу, и (ЧРЕЗВЫЧАЙНО ВАЖНО) должны содержать стандартное системное сообщение об ошибке о том, что пошло не так. Вот простой, но достаточный пример:

  opendir(my $dh, $dir)        or die "can't opendir $dir: $!";

• Выравнивайте свои транслитерации, когда это имеет смысл:

  tr [abc]
     [xyz];

• Подумайте о повторном использовании. Зачем тратить умственные усилия на одноразовую задачу, когда вы можете захотеть сделать что-то подобное снова? Подумайте о обобщении кода. Подумайте о написании модуля или класса объектов. Подумайте о том, чтобы ваш код работал чисто с use strict и use warnings в действии. Подумайте о раздаче своего кода. Подумайте о изменении своего мировоззрения. Подумайте… ладно, не стоит.

• Постарайтесь документировать свой код и использовать форматирование Pod последовательно. Вот распространённые ожидаемые соглашения:

  • Используйте C<> для имён функций, переменных и модулей (и в более общем смысле, для всего, что можно считать частью кода, например, для дескрипторов файлов или конкретных значений). Обратите внимание, что имена функций считаются более читаемыми со скобками после их имени, то есть function().

  • Используйте B<> для имён команд, таких как cat или grep.

  • Используйте F<> или C<> для имён файлов. F<> должен быть единственным кодом Pod для имён файлов, но так как большинство форматировщиков Pod отображают его как курсив, пути Unix и Windows с их косыми чертами и обратными косыми чертами могут быть менее читаемыми, и их лучше отображать с помощью C<>.

• Будьте последовательны.

• Будьте вежливы.