perlstyle

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ОПИСАНИЕ

НАЗВАНИЕ

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

ОПИСАНИЕ

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

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

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

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

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

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

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

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

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

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

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

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

• Непривязанные операторы else.

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

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

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

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

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

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

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

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

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

  open(FOO,$foo) || die "Can't open $foo: $!";

  лучше, чем

  die "Can't open $foo: $!" unless open(FOO,$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()) или `backticks` в контексте без значения, то есть когда вы просто отбрасываете их возвращаемые значения. Эти функции все возвращают значения, поэтому используйте их. В противном случае используйте цикл 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(D, $dir)     or die "can't opendir $dir: $!";

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

  tr [abc]
     [xyz];

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

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

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

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

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

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

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