perlmodstyle

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ВВЕДЕНИЕ
• БЫСТРЫЙ СПИСОК ПРОВЕРКИ
  • Перед началом
  • API
  • Стабильность
  • Документация
  • Соображения по выпуску
• ПЕРЕД НАЧАЛОМ РАЗРАБОТКИ МОДУЛЯ
  • Было ли это сделано раньше?
  • Делать одно и делать хорошо
  • Что в имени?
  • Получите отзывы перед публикацией
• ПРОЕКТИРОВАНИЕ И НАПИСАНИЕ ВАШЕГО МОДУЛЯ
  • Быть или не быть объектно-ориентированным?
  • Проектирование вашего API
  • Строгость и предупреждения
  • Обратная совместимость
  • Обработка ошибок и сообщения
• ДОКУМЕНТИРОВАНИЕ ВАШЕГО МОДУЛЯ
  • POD
  • README, INSTALL, заметки о выпуске, журналы изменений
• СООБРАЖЕНИЯ ПО ВЫПУСКУ
  • Нумерация версий
  • Предварительные требования
  • Тестирование
  • Упаковка
  • Лицензирование
• ОБЩИЕ ОШИБКИ
  • Переизобретение колеса
  • Попытка сделать слишком много
  • Неподходящая документация
• СМОТРИТЕ ТАКЖЕ
• АВТОР

НАЗВАНИЕ

perlmodstyle - Руководство по стилю Perl-модулей

ВВЕДЕНИЕ

В данном документе описывается "лучшая практика" сообщества Perl для написания Perl-модулей. Он расширяет рекомендации, содержащиеся в perlstyle, которые следует считать обязательным чтением перед чтением этого документа.

Хотя этот документ предназначен для всех авторов модулей, он особенно ориентирован на авторов, которые хотят опубликовать свои модули на CPAN.

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

Этот документ отличается от perlnewmod тем, что это руководство по стилю, а не учебное пособие по созданию CPAN-модулей. Он предоставляет контрольный список, с помощью которого можно сравнить модули, чтобы определить, соответствуют ли они лучшим практикам, без необходимости подробно описывать, как этого добиться.

Все советы, содержащиеся в этом документе, были получены из обширных бесед с опытными авторами и пользователями CPAN. Каждый совет, данный здесь, является результатом предыдущих ошибок. Эта информация поможет вам избежать тех же ошибок и дополнительной работы, которая неизбежно потребовалась бы для их исправления.

Первая часть этого документа предоставляет перечень элементов списка; последующие разделы содержат более подробное обсуждение пунктов в списке. В заключительном разделе "Общие ошибки" описаны некоторые из самых распространенных ошибок, допущенных авторами CPAN.

БЫСТРЫЙ СПИСОК ПРОВЕРКИ

Для более подробной информации по каждому пункту этого списка см. ниже.

Перед началом

• Не переизобретайте колесо

• Исправлять, расширять или наследовать существующий модуль, где это возможно

• Делать одно и делать хорошо

• Выбрать подходящее имя

• Получить обратную связь перед публикацией

API

• API должен быть понятен среднему программисту

• Простые методы для простых задач

• Разделение функциональности от вывода

• Согласованное именование подпрограмм или методов

• Использование именованных параметров (хэш или hashref), когда параметров больше двух

Стабильность

• Убедитесь, что ваш модуль работает под use strict и -w

• Стабильные модули должны поддерживать обратную совместимость

Документация

• Пишите документацию в POD

• Документируйте цель, область и целевые приложения

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

• Приводите примеры использования в документации

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

• Предоставляйте ссылки на дополнительную информацию (URL, электронную почту)

Соображения по выпуску

• Укажите предварительные требования в Makefile.PL или Build.PL

• Укажите требования к версии Perl с помощью use

• Включите тесты с вашим модулем

• Выберите разумную и согласованную схему нумерации версий (X.YY — это обычная схема нумерации Perl-модулей)

• Увеличивайте номер версии для каждого изменения, независимо от его размера

• Упакуйте модуль с помощью "make dist"

• Выберите подходящую лицензию (GPL/Artistic — хороший вариант по умолчанию)

ПЕРЕД НАЧАЛОМ РАЗРАБОТКИ МОДУЛЯ

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

Было ли это сделано раньше?

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

Хорошие места для поиска существующих модулей включают MetaCPAN и PrePAN, а также вопросы на module-authors@perl.org (https://lists.perl.org/list/module-authors.html).

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

Делать одно и делать хорошо

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

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

Плохой пример:

"FooBar.pm предоставляет реализацию протокола FOO и связанного стандарта BAR."

Хороший пример:

"Foo.pm предоставляет реализацию протокола FOO. Bar.pm реализует связанный протокол BAR."

Это означает, что если разработчик нуждается только в модуле для стандарта BAR, он не должен быть вынужден устанавливать библиотеки для FOO тоже.

Что в имени?

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

При выборе имени модуля, учтите следующее:

• Быть описательным (т.е. точно описывать назначение модуля).

• Быть согласованным с существующими модулями.

• Отражать функциональность модуля, а не его реализацию.

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

Получите отзывы перед публикацией

Если вы никогда раньше не загружали модуль на CPAN (и даже если загружали), настоятельно рекомендуется получить обратную связь на PrePAN. PrePAN — это сайт, посвящённый обсуждению идей для CPAN-модулей с другими разработчиками Perl, и это отличный ресурс для новых (и опытных) разработчиков Perl.

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

ПРОЕКТИРОВАНИЕ И НАПИСАНИЕ ВАШЕГО МОДУЛЯ

Соображения по проектированию и кодированию модуля:

Быть или не быть объектно-ориентированным?

Ваш модуль может быть объектно-ориентированным (ОО) или нет, или он может иметь оба вида интерфейсов. Есть плюсы и минусы каждого метода, которые следует учитывать при проектировании вашего API.

В руководстве по "Лучшим практикам Perl" (2004 год, издательство O'Reilly Media, Inc.) Damian Conway предоставляет список критериев, которые следует использовать при принятии решения о том, подходит ли ОО для вашей задачи:

• Разрабатываемая система большая или, вероятно, станет большой.

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

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

• У вас есть данные, к которым применяются многие разные операции.

• Вам нужно выполнять одни и те же общие операции над связанными типами данных, но с небольшими вариациями в зависимости от конкретного типа данных, к которому применяются операции.

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

• Типичные взаимодействия между данными лучше всего представляются операторами.

• Реализация отдельных компонентов системы, вероятно, будет меняться со временем.

• Проектирование системы уже ориентировано на объекты.

• Ваши модули кода будут использоваться большим количеством других программистов.

Внимательно подумайте, подходит ли ООП для вашего модуля. Необоснованное использование объектно-ориентированного подхода приводит к сложным API, которые трудно понять и использовать среднему пользователю модуля.

Проектирование вашего API

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

Создание простых процедур для выполнения простых задач.

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

Разделение функциональности от вывода.

Возвращайте результаты в максимально общем виде и позволяйте пользователю выбирать, как их использовать. Наиболее общий вид обычно представляет собой структуру данных Perl, которая может быть использована для генерации текстового отчета, HTML, XML, запроса к базе данных или чего-либо еще, что требуется вашим пользователям.

Если ваша процедура итерирует по списку (например, списку файлов или записей в базе данных), вы можете рассмотреть возможность предоставления обратного вызова, чтобы пользователи могли манипулировать каждым элементом списка по очереди. File::Find предоставляет пример этого с помощью синтаксиса find(\&wanted, $dir).

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

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

Правила именования

Ваше именование должно быть последовательным. Например, лучше иметь:

display_day();
display_week();
display_year();

чем

display_day();
week_display();
show_year();

Это относится в равной степени к именам методов, именам параметров и всему остальному, что видно пользователю (и большинству того, что не видно!).

Передача параметров

Используйте именованные параметры. Гораздо удобнее использовать хеш-таблицу:

$obj->do_something(
        name => "wibble",
        type => "text",
        size => 1024,
);

... чем иметь длинный список неименованных параметров, например:

$obj->do_something("wibble", "text", 1024);

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

$obj->do_something(undef, undef, undef, undef, undef, 1024);

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

Вопрос о том, передавать аргументы в хеш или хеш-ссылке, в основном зависит от личных предпочтений.

Использование ключей хеша, начинающихся с тире (-name) или полностью заглавных (NAME), является пережитком более ранних версий Perl, в которых обычные строчные строки не обрабатывались должным образом оператором =>. Хотя некоторые модули сохраняют ключи аргументов в верхнем регистре или с тире по историческим причинам или по личным предпочтениям, большинство новых модулей должны использовать простые строчные ключи. Что бы вы ни выбрали, будьте последовательны!

Строгость и предупреждения

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

Обратная совместимость

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

Обработка ошибок и сообщений

Когда ваш модуль обнаруживает ошибку, он должен сделать одно или несколько из следующего:

• Возвратить неопределенное значение.

• Установить $Module::errstr или аналогичное (errstr — общее имя, используемое модулями DBI и другими популярными модулями; если вы выберете что-то другое, четко продокументируйте это).

• warn() или carp() сообщение в STDERR.

• croak() только когда ваш модуль совершенно не может понять, что делать. (croak() — лучшая версия die() для использования внутри модулей, которая сообщает об ошибках с точки зрения вызывающей стороны. См. Carp для получения подробной информации о croak(), carp() и других полезных процедурах.)

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

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

ДОКУМЕНТИРОВАНИЕ ВАШЕГО МОДУЛЯ

POD

Ваш модуль должен включать документацию, предназначенную для разработчиков Perl. Для общей технической документации вы должны использовать «простую старую документацию» Perl (POD), хотя вы можете захотеть написать дополнительную документацию (белые книги, руководства и т. д.) в другом формате. Вам нужно охватить следующие темы:

• Краткое описание общих применений модуля

• Цель, область применения и целевые приложения вашего модуля

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

• Примеры использования

• Источники дополнительной информации

• Электронный адрес автора/поддерживающего лица

Уровень подробности в документации модуля Perl обычно уменьшается от менее подробных к более подробным. В разделе SYNOPSIS должен быть приведен минимальный пример использования (возможно, всего одна строка кода; пропустите необычные случаи использования или все, что не нужно большинству пользователей); в разделе DESCRIPTION должен быть дан общий обзор вашего модуля, как правило, всего в нескольких абзацах; более подробные сведения о методах или подпрограммах модуля, длинные примеры кода или другая подробная информация должны быть приведены в последующих разделах.

В идеале, тот, кто немного знаком с вашим модулем, должен иметь возможность освежить свои знания, не нажимая на клавишу «страница вниз». По мере того, как читатель продолжает проходить по документу, он должен получать всё больше и больше знаний.

Рекомендуемый порядок разделов в документации модуля Perl:

• НАЗВАНИЕ

• СИНОПСИС

• ОПИСАНИЕ

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

• ОШИБКИ/ЗАМЕЧАНИЯ/и т.д.

• АВТОР

• СМОТРИТЕ ТАКЖЕ

• АВТОРСКИЕ ПРАВА и ЛИЦЕНЗИЯ

Держите свою документацию рядом с кодом, который она документирует («встроенная» документация). Включите POD для данного метода непосредственно над подпрограммой этого метода. Это упрощает обновление документации и позволяет избежать необходимости документировать каждый фрагмент кода дважды (один раз в POD и один раз в комментариях).

README, INSTALL, заметки о релизе, журналы изменений

Ваш модуль также должен включать файл README, описывающий модуль и дающий ссылки на дополнительную информацию (веб-сайт, электронная почта автора).

Файл INSTALL должен быть включен и должен содержать простые инструкции по установке. При использовании ExtUtils::MakeMaker это обычно будет:

perl Makefile.PL

make

make test

make install

При использовании Module::Build это обычно будет:

perl Build.PL

perl Build

perl Build test

perl Build install

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

Если у вас нет веских причин использовать другой формат (например, формат, используемый в вашей компании), принято называть ваш файл журнала изменений Changes, и следовать простому формату, описанному в CPAN::Changes::Spec.

СООБРАЖЕНИЯ ПО ВЫПУСКУ

Нумерация версий

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

Наиболее распространенная схема нумерации версий CPAN выглядит следующим образом:

1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32

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

perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' \
                                                        'Foo.pm'

Если вы хотите выпустить «бета» или «альфа» версию модуля, но не хотите, чтобы CPAN.pm отображал ее как последнюю, используйте «_» после обычного номера версии, за которым следуют как минимум две цифры, например 1.20_01. Если вы делаете это, рекомендуется использовать следующий фрагмент кода:

our $VERSION = "1.12_01"; # so CPAN distribution will have
                          # right filename
our $XS_VERSION = $VERSION; # only needed if you have XS code
$VERSION = eval $VERSION; # so "use Module 0.002" won't warn on
                          # underscore

В этом случае MakeMaker прочитает только первую строку и, таким образом, прочитает знак подчёркивания, а интерпретатор Perl оценит $VERSION и преобразует строку в число. Более поздние операции, которые обрабатывают $VERSION как число, смогут сделать это, не вызывая предупреждения о том, что $VERSION не является числом.

Никогда не выпускайте ничего (даже исправление документации из одного слова) без увеличения номера. Даже исправление документации из одного слова должно привести к изменению версии на уровне подвторостепенной.

После выбора важно придерживаться схемы версий, не уменьшая количество цифр. Это потому, что пакетные инструменты «ниже по течению», такие как система портов FreeBSD, интерпретируют номера версий различными способами. Если вы измените количество цифр в своей схеме версий, вы можете сбить с толку эти системы, так что они получат версии вашего модуля в неправильном порядке, что, очевидно, плохо.

Предварительные требования

Авторы модулей должны тщательно продумать, стоит ли полагаться на другие модули и на какие.

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

• Ядровые модули Perl

• Стабильные модули CPAN

• Нестабильные модули CPAN

• Модули, недоступные из CPAN

Укажите требования к версиям других модулей Perl в предварительных требованиях в файлах Makefile.PL или Build.PL.

Не забудьте указать требования к версии Perl как в Makefile.PL или Build.PL, так и с помощью require 5.6.1, или аналогичных. Подробности см. в разделе use VERSION "require" в perlfunc.

Тестирование

Все модули должны быть протестированы перед распространением (с помощью «make disttest»), а тесты также должны быть доступны пользователям, устанавливающим модули (с помощью «make test»). Для Module::Build вы бы использовали эквивалент make test perl Build test.

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

Полезные модули для написания тестов (с минимальным влиянием на процесс разработки и время) включают Test::Simple, Carp::Assert и Test::Inline. Для более сложных наборов тестов есть Test::More и Test::MockObject.

Упаковку

Модули должны быть упакованы с использованием одного из стандартных инструментов упаковки. В настоящее время у вас есть выбор между ExtUtils::MakeMaker и более независимым от платформы Module::Build, позволяющим модулям устанавливаться согласованным образом. При использовании ExtUtils::MakeMaker вы можете использовать «make dist», чтобы создать свой пакет. Существуют инструменты, которые помогут вам собрать ваш модуль в стиле MakeMaker. К ним относятся ExtUtils::ModuleMaker и h2xs. См. также perlnewmod.

Лицензирование

Убедитесь, что ваш модуль имеет лицензию и что полный текст ее включен в дистрибутив (если это не распространенная лицензия и условия лицензии не требуют ее включения).

Если вы не знаете, какую лицензию использовать, двойная лицензия под GPL и Artistic (такая же, как и у самого Perl) — хорошая идея. См. perlgpl и perlartistic.

ОБЩИЕ ОШИБКИ

Переизобретение велосипеда

Существуют определенные области применения, которые уже очень хорошо поддерживаются CPAN. Один пример — системы шаблонов, другой — модули дат и времени, и их гораздо больше. Хотя писать свою собственную версию этих вещей — своего рода посвящение, пожалуйста, тщательно обдумайте, действительно ли Perl-мир нуждается в вашем опубликованном модуле.

Попытка сделать слишком много

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

Неподходящая документация

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

Учебники, документация для конечных пользователей, научные статьи, часто задаваемые вопросы и т. д. не подходят для основной документации модуля. Если вы действительно хотите написать их, включите их как поддокументы, такие как My::Module::Tutorial или My::Module::FAQ, и предоставьте ссылку в разделе «См. также» основной документации.

СМОТРИТЕ ТАКЖЕ

perlstyle

Общие рекомендации по стилю Perl

perlnewmod

Как создать новый модуль

perlpod

Документация POD

podchecker

Проверяет правильность вашего POD

Инструменты упаковки

ExtUtils::MakeMaker, Module::Build

Инструменты тестирования

Test::Simple, Test::Inline, Carp::Assert, Test::More, Test::MockObject

https://pause.perl.org/

Сервер загрузки авторов Perl. Содержит ссылки на информацию для авторов модулей.

Любая хорошая книга по программной инженерии

АВТОР

Kirrily "Skud" Robert <skud@cpan.org>