perlmodstyle-クラウドでのオンライン

プログラム：

NAME

perlmodstyle-Perlモジュールスタイルガイド

はじめに

このドキュメントでは、Perlを作成するためのPerlコミュニティの「ベストプラクティス」について説明します。
モジュール。 これは、perlstyleにある推奨事項を拡張したものであり、考慮する必要があります。
このドキュメントを読む前に読む必要があります。

このドキュメントは、すべてのモジュール作成者に役立つことを目的としていますが、特に
モジュールをCPANで公開したい作者を対象としています。

焦点は、モジュールのユーザーに見えるスタイルの要素ではなく、
モジュールの開発者だけが見ることができる部分。 ただし、
このドキュメントに示されているガイドラインは、外挿して、
モジュールの内部。

このドキュメントは、チュートリアルではなくスタイルガイドであるという点でperlnewmodとは異なります。
CPANモジュールの作成について。 モジュールを比較できるチェックリストを提供します
必ずしも説明することなく、それらがベストプラクティスに準拠しているかどうかを判断する
これを達成する方法を詳しく説明します。

このドキュメントに含まれるすべてのアドバイスは、広範な会話から収集されました
経験豊富なCPANの作者とユーザーと。 ここで与えられるアドバイスはすべて結果です
以前の間違いの。 この情報は、同じ間違いを回避するのに役立つためにここにあります
それらを修正するために必然的に必要となる余分な作業。

このドキュメントの最初のセクションでは、項目別のチェックリストを提供します。 以降のセクション
リストの項目のより詳細な議論を提供します。 最後のセクション「共通
落とし穴」では、CPANの作成者が犯した最も一般的な間違いのいくつかについて説明しています。

QUICK チェックリスト

このチェックリストの各項目の詳細については、以下を参照してください。

前 フォーム start
・車輪の再発明をしないでください

・可能な場合、既存のモジュールにパッチを適用、拡張、またはサブクラス化する

・一つのことをして、それをうまくやる

・適切な名前を選択してください

・公開する前にフィードバックを得る

この API
・APIは、平均的なプログラマーが理解できる必要があります

・単純なタスクのための単純な方法

・機能を出力から分離する

・サブルーチンまたはメソッドの一貫した命名

・XNUMXつ以上のパラメーターがある場合は、名前付きパラメーター（hashまたはhashref）を使用します

安定性
・モジュールが「usestrict」および「-w」で動作することを確認します

・安定したモジュールは下位互換性を維持する必要があります

ドキュメント
・PODでドキュメントを書く

・目的、範囲、および対象となるアプリケーションを文書化する

・パラメータとリターンを含む、公的にアクセス可能な各メソッドまたはサブルーチンを文書化します
値

・ドキュメントでの使用例を挙げてください

・READMEファイルを提供し、おそらくリリースノート、変更ログなども提供します

・詳細情報（URL、電子メール）へのリンクを提供します

リリース 検討事項
・Makefile.PLまたはBuild.PLで前提条件を指定します

・「use」でPerlのバージョン要件を指定する

・モジュールにテストを含める

・賢明で一貫性のあるバージョン番号付けスキームを選択します（X.YYは一般的なPerlです
モジュール番号付けスキーム）

・どんなに小さくても、変更のたびにバージョン番号を増やします

・「makedist」を使用してモジュールをパッケージ化します

・適切なライセンスを選択します（GPL / Artisticが適切なデフォルトです）

BEFORE 皆様のおかげで 開始 書き込み A モジュール

時間をかけて考えずに、モジュールの開発に真っ向から立ち向かわないようにしてください
最初。 少し先を見越して、後で多大な労力を節約できるかもしれません。

ています it き 行われ 前？
モジュールを作成する必要さえないかもしれません。 それがすでにPerlで行われているかどうかを確認してください。
正当な理由がない限り、車輪の再発明は避けてください。

既存のモジュールを探すのに適した場所は次のとおりです。http://search.cpan.org/>および
と尋ねる[メール保護]"
(<http://lists.perl.org/list/module-authors.html>）。

既存のモジュールの場合 ほとんど あなたが望むことをします、パッチを書くことを考えてください、
サブクラス、または既存のモジュールを書き換えるのではなく拡張する。

Do XNUMXつ もの と do it よく
明らかなことを述べるリスクを冒して、モジュールはモジュール式であることが意図されています。 Perl開発者
モジュールを使用して、アプリケーションの構成要素をまとめることができる必要があります。
ただし、ブロックが正しい形状であり、開発者が正しい形状であることが重要です。
必要なのが小さなブロックだけの場合は、大きなブロックを使用する必要はありません。

モジュールには、XNUMX文以内の明確に定義されたスコープが必要です。
モジュールを関連するモジュールのファミリーに分解できますか？

悪い例：

「FooBar.pmは、FOOプロトコルと関連するBAR標準の実装を提供します。」

良い例え：

「Foo.pmはFOOプロトコルの実装を提供します。Bar.pmは関連するBARを実装します
プロトコル。"

つまり、開発者がBAR標準のモジュールのみを必要とする場合、開発者は必要ありません。
FOO用のライブラリもインストールする必要があります。

何 in a 名？
早い段階でモジュールに適切な名前を選択するようにしてください。 これは人々を助けます
モジュールを見つけて覚え、モジュールを使ったプログラミングをより直感的にします。

モジュールに名前を付けるときは、次のことを考慮してください。

・説明的である（つまり、モジュールの目的を正確に説明する）。

・既存のモジュールと一貫性を保つ。

・実装ではなく、モジュールの機能を反映します。

・特に適切な階層がすでに存在する場合は、新しい最上位階層を開始しないでください
モジュールを配置できる場所が存在します。

以上 フィードバック 出版
これまでにモジュールをCPANにアップロードしたことがない場合（およびアップロードした場合でも）、
PrePANに関するフィードバックを得るよう強くお勧めしますhttp://prepan.org>。 PrePANはサイトです
他のPerl開発者とCPANモジュールのアイデアについて話し合うことに専念しており、素晴らしいです
新しい（そして経験豊富な）Perl開発者のためのリソース。

また、モジュールのにすでに精通している人々からフィードバックを得るようにしてください。
アプリケーションドメインとCPANネーミングシステム。 同様のモジュール、またはモジュールの作成者
Perl Monksのようなコミュニティサイトと同様に、似たような名前で始めるのが良いかもしれません。
<http://www.perlmonks.org>.

設計 そして 書き込み サプライヤ モジュール

モジュールの設計とコーディングに関する考慮事項：

に OO or 〜へ OO？
モジュールはオブジェクト指向（OO）であるかどうか、または両方の種類のインターフェースを備えている可能性があります
利用可能。 それぞれのテクニックには長所と短所があります。
APIを設計します。

In パール おすすめ！ プラクティス （著作権2004、O'Reilly Media、Inc.発行）、Damian Conway
OOが問題に適切であるかどうかを判断するときに使用する基準のリストを提供します。

・設計中のシステムが大きい、または大きくなる可能性があります。

・データは、特に大規模なものがある場合、明白な構造に集約できます
各集計のデータ量。

・さまざまなタイプのデータ集合体は、使用を容易にする自然な階層を形成します
継承とポリモーフィズムの。

・さまざまな操作が適用されるデータがあります。

・関連するタイプのデータに対して同じ一般的な操作を実行する必要がありますが、
操作が適用される特定のタイプのデータに応じてわずかに異なります
に。

・後で新しいデータ型を追加する必要がある可能性があります。

・データ間の一般的な相互作用は、演算子によって最もよく表されます。

・システムの個々のコンポーネントの実装は変更される可能性があります
時間。

・システム設計はすでにオブジェクト指向です。

・他の多くのプログラマーがあなたのコードモジュールを使用します。

OOがモジュールに適しているかどうかを慎重に検討してください。 無償オブジェクト
オリエンテーションにより、平均的なモジュールユーザーが行うのが難しい複雑なAPIが生成されます
理解または使用します。

設計 API
あなたのインターフェースは、平均的なPerlプログラマーが理解できるはずです。 以下
ガイドラインは、APIが十分に単純であるかどうかを判断するのに役立つ場合があります。

簡単なことをするための簡単なルーチンを書いてください。
いくつかのモノリシックなルーチンよりも、多数の単純なルーチンを使用する方が適切です。 もしあなたの
ルーチンはその引数に基づいてその動作を大幅に変更します、それはその兆候です
XNUMXつ（またはそれ以上）の別々のルーチンが必要です。

機能を出力から分離します。
可能な限り最も一般的な形式で結果を返し、ユーザーが方法を選択できるようにします
それらを使用します。 可能な最も一般的な形式は通常、Perlデータ構造です。
次に、テキストレポート、HTML、XML、データベースクエリなどを生成するために使用できます
それ以外の場合は、ユーザーが必要とします。

ルーチンがある種のリスト（ファイルのリスト、または
データベース内のレコード）ユーザーができるようにコールバックを提供することを検討できます
リストの各要素を順番に操作します。 File::Findはこの例を提供します
「find（\＆wanted、$ dir）」構文を使用します。

賢明なショートカットとデフォルトを提供します。
シンプルなものを実現するために、すべてのモジュールユーザーが同じフープをジャンプする必要はありません
結果。 より複雑なまたはより複雑なオプションのパラメータまたはルーチンをいつでも含めることができます
非標準的な動作。 ほとんどのユーザーがほぼ同じものをいくつか入力する必要がある場合
モジュールの使用を開始するときのコード行は、作成する必要があることを示しています。
その動作はデフォルトです。 デフォルトを使用する必要があることを示すもうXNUMXつの良い指標は、
ほとんどのユーザーは、同じ引数を使用してルーチンを呼び出します。

命名規則
命名は一貫している必要があります。 たとえば、次のようにするとよいでしょう。

display_day（）;
display_week（）;
display_year（）;

より

display_day（）;
week_display（）;
show_year（）;

これは、メソッド名、パラメーター名、およびその他すべてに等しく適用されます。
ユーザーに表示されます（そして表示されないほとんどのもの！）

パラメータの受け渡し
名前付きパラメーターを使用します。 次のようなハッシュを使用する方が簡単です。

$ obj-> do_something（
名前=>"wibble"、
タイプ=>「テキスト」、
サイズ=>1024、
);

...次のような名前のないパラメータの長いリストを作成するよりも：

$ obj-> do_something（ "wibble"、 "text"、1024）;

引数のリストは、XNUMXつ、XNUMXつ、またはXNUMXつの引数に対しては正常に機能する可能性がありますが、
モジュールユーザーが覚えるのが難しくなり、モジュールにとってより多くの引数が難しくなります
管理する作者。 新しいパラメータを追加する場合は、に追加する必要があります
下位互換性のためにリストの最後にあります。これにより、おそらくリストが作成されます。
直感的でない注文。 また、多くの要素が未定義である可能性がある場合は、次のように表示される可能性があります
魅力のないメソッド呼び出し：

$ obj-> do_something（undef、undef、undef、undef、undef、1024）;

それらを持つパラメータに適切なデフォルトを提供します。 ユーザーを作らないでください
ほとんどの場合同じになるパラメータを指定します。

引数をハッシュとhashrefのどちらで渡すかという問題は、主に問題です。
個人的なスタイルの。

ハイフン（ "-name"）で始まる、または完全に大文字のハッシュキーの使用
（"NAME"）は、通常の小文字の文字列が含まれる古いバージョンのPerlの遺物です。
「=>」演算子によって正しく処理されませんでした。 一部のモジュールは大文字を保持しますが
または、歴史的な理由または個人的なスタイルの問題として、ハイフンでつながれた引数キー、
ほとんどの新しいモジュールは、単純な小文字のキーを使用する必要があります。 何を選んでも、
一貫性のある！

厳密さ と 警告
モジュールは厳密なプラグマの下で正常に実行され、なしで実行される必要があります
警告を生成します。 モジュールは、必要に応じて汚染チェックも処理する必要があります。
多くの場合、これは問題を引き起こす可能性がありますが。

後方 互換性
「安定した」モジュールは、少なくとも
長い移行フェーズとバージョン番号の大幅な変更。

エラー 取り扱い と メッセージ
モジュールでエラーが発生した場合、次のXNUMXつ以上を実行する必要があります。

・未定義の値を返します。

・$ Module :: errstrまたは同様のものを設定します（「errstr」は、DBIおよびその他で使用される一般名です。
人気のあるモジュール。 他のものを選択する場合は、必ず明確に文書化してください）。

・STDERRへのメッセージ「warn（）」または「carp（）」。

・モジュールが何をすべきかを完全に理解できない場合にのみ「croak（）」。 （"croak（）"
モジュール内で使用するための「die（）」のより良いバージョンであり、
発信者の視点。 「croak（）」、「carp（）」などの詳細については、Carpを参照してください。
便利なルーチン。）

・上記の代わりに、エラーを使用して例外をスローすることをお勧めします
モジュールを開きます。

構成可能なエラー処理は、ユーザーにとって非常に便利です。 選択肢を提供することを検討してください
警告メッセージとデバッグメッセージのレベルの一覧、メッセージを別のファイルに送信するオプション、
エラー処理ルーチン、または他のそのような機能を指定する方法。 必ずデフォルトですべて
これらのオプションは最も一般的に使用されます。

文書化 サプライヤ モジュール

POD
モジュールには、Perl開発者向けのドキュメントを含める必要があります。 Perlを使用する必要があります
一般的な技術文書の「PlainOldDocumentation」（POD）。
他のいくつかのドキュメント（ホワイトペーパー、チュートリアルなど）を書きたい
フォーマット。 次の主題をカバーする必要があります。

・モジュールの一般的な使用法の概要

・モジュールの目的、範囲、およびターゲットアプリケーション

・パラメータとを含む、公的にアクセス可能な各メソッドまたはサブルーチンの使用
戻り値

・使用例

・詳細情報のソース

・作成者/メンテナの連絡先メールアドレス

Perlモジュールのドキュメントの詳細レベルは、通常、詳細度が低いものから詳細なものへと変化します。
詳細。 概要セクションには、最小限の使用例が含まれている必要があります（おそらく
わずかXNUMX行のコード。 異常なユースケースやほとんどの人が必要としないものをスキップする
ユーザー）; 説明では、モジュールを大まかに説明する必要があります。
いくつかの段落; モジュールのルーチンまたはメソッドの詳細、長いコード例、または
その他の詳細な資料は、後続のセクションで説明する必要があります。

理想的には、モジュールに少し精通している人が自分のモジュールを更新できる必要があります
「ページダウン」を押さずにメモリ。 読者がドキュメントを読み続けると、
徐々に多くの知識を受け取る必要があります。

Perlモジュールのドキュメントで推奨されるセクションの順序は次のとおりです。

・ 名前

・概要

・ 説明

・利用可能な方法の詳細を示すXNUMXつ以上のセクションまたはサブセクション
ルーチンおよびその他の関連情報。

・バグ/警告/など

・ 著者

・関連項目

・著作権とライセンス

ドキュメントをドキュメント化するコードの近くに保管します（「インライン」ドキュメント）。 PODを含める
そのメソッドのサブルーチンのすぐ上の特定のメソッドに対して。 これにより、
ドキュメントを最新のものにし、コードの各部分をXNUMX回ドキュメント化する必要をなくします（XNUMX回は
PODとコメントで一度）。

README、 インストール、 リリース ノート、 チェンジログ
モジュールには、モジュールを説明し、へのポインタを与えるREADMEファイルも含める必要があります
詳細情報（ウェブサイト、著者の電子メール）。

INSTALLファイルが含まれている必要があり、簡単なインストール手順が含まれている必要があります。
ExtUtils :: MakeMakerを使用する場合、これは通常次のようになります。

perl Makefile.PL
make
テストを行う
make installを

Module :: Buildを使用する場合、これは通常次のようになります。

perl Build.PL
perlビルド
perlビルドテスト
perlビルドインストール

ソフトウェアのリリースごとにリリースノートまたは変更ログを作成する必要があります
ユーザーに関連する用語で、モジュールに対するユーザーに表示される変更を説明します。

他の形式（たとえば、使用されている形式）を使用する正当な理由がない限り
社内）では、慣例として、変更ログファイルに「変更」という名前を付けます。
CPAN :: Changes::Specで説明されている単純な形式に従います。

RELEASE 考慮事項

ナンバリング
バージョン番号は、少なくともメジャーリリースとマイナーリリース、場合によってはサブマイナーリリースを示す必要があります
リリース。 メジャーリリースとは、ほとんどの機能が変更されたリリース、または
どの主要な新機能が追加されますか。 マイナーリリースとは、少量のリリースです。
機能が追加または変更されました。 サブマイナーバージョン番号は通常、
ドキュメントパッチなど、機能に影響を与えない変更。

最も一般的なCPANバージョンの番号付けスキームは次のようになります。

1.00、1.10、1.11、1.20、1.30、1.31、1.32

正しいCPANバージョン番号は、
XNUMX進数。 を使用して、CPANに準拠しているかどうかをテストできます

perl -MExtUtils :: MakeMaker -le'print MM-> parse_version（shift）''Foo.pm'

モジュールの「ベータ」または「アルファ」バージョンをリリースしたいが、CPAN.pmをリリースしたくない場合
通常のバージョン番号の後に「_」を使用し、その後に少なくとも2つを使用するようにリストします。
数字、例えば。 1.20_01。 これを行う場合は、次のイディオムをお勧めします。

$ VERSION = "1.12_01"; ＃CPANディストリビューションは
＃正しいファイル名
$ XS_VERSION = $ VERSION; ＃XSコードがある場合にのみ必要
$ VERSION = eval $ VERSION; ＃「モジュール0.002を使用」は警告しません
＃アンダースコア

そのトリックを使用すると、MakeMakerは最初の行のみを読み取り、アンダースコアを読み取ります。
一方、perlインタプリタは$ VERSIONを評価し、文字列を
番号。 $ VERSIONを数値として扱う後の操作では、そうすることができます。
$VERSIONが数値ではないという警告を発することなく。

増分せずに何も（XNUMX語のドキュメントパッチでさえ）リリースしないでください
番号。 XNUMX語のドキュメントパッチでも、バージョンが変更されるはずです。
サブマイナーレベル。

選択したら、数を減らすことなく、バージョンスキームに固執することが重要です
桁の。 これは、FreeBSDポートシステムなどの「ダウンストリーム」パッケージャーが
バージョン番号をさまざまな方法で解釈します。 の桁数を変更した場合
バージョンスキームでは、これらのシステムを混乱させて、モジュールのバージョンを取得することができます
明らかに悪い秩序の。

前提条件
モジュールの作成者は、他のモジュールに依存するかどうか、およびどのモジュールに依存するかを慎重に検討する必要があります
依存するモジュール。

最も重要なことは、可能な限り安定したモジュールを選択することです。 優先順に：

・コアPerlモジュール

・安定したCPANモジュール

・不安定なCPANモジュール

・CPANから利用できないモジュール

の前提条件で他のPerlモジュールのバージョン要件を指定します
Makefile.PLまたはBuild.PL。

Makefile.PLまたはBuild.PLの両方でPerlのバージョン要件を指定してください。
「5.6.1が必要」など。 perlfuncの「require」の「useVERSION」のセクションを参照してください。
詳細。

テスト
すべてのモジュールは、配布前に（ "make disttest"を使用して）テストする必要があります。
モジュールをインストールする人も利用できるようにする必要があります（「maketest」を使用）。 にとって
Module :: Buildは、「maketest」と同等の「perlBuildtest」を使用します。

これらのテストの重要性は、モジュールの安定性の主張に比例します。 A
安定していると主張するモジュール、または幅広い使用を実現したいモジュールは、次のように準拠する必要があります。
可能な限り厳密なテスト体制。

テストの作成に役立つ便利なモジュール（開発プロセスへの影響を最小限に抑えます。
あなたの時間）には、Test :: Simple、Carp :: Assert、Test::Inlineが含まれます。 より洗練されたもののために
テストスイートには、Test::MoreとTest::MockObjectがあります。

梱包
モジュールは、標準のパッケージツールのXNUMXつを使用してパッケージ化する必要があります。 現在あなたは
ExtUtils::MakeMakerとよりプラットフォームに依存しないModule::Build、
モジュールを一貫した方法でインストールできるようにします。 ExtUtils :: MakeMakerを使用する場合、
「makedist」を使用してパッケージを作成できます。 を構築するのに役立つツールが存在します
MakeMakerに適したスタイルのモジュール。 これらには、ExtUtils::ModuleMakerおよびh2xsが含まれます。 見る
また、perlnewmod。

ライセンシング
モジュールにライセンスがあり、その全文が
配布（一般的なものであり、ライセンスの条件で要求されていない場合を除く）
それを含める）。

使用するライセンスがわからない場合は、GPLライセンスとArtisticライセンスのデュアルライセンス
（Perl自体と同じ）良い考えです。 perlgplおよびperlartisticを参照してください。

COMMON ピットフォール

再発明 　 ホイール
すでにCPANによって非常によく提供されている特定のアプリケーションスペースがあります。
XNUMXつの例はテンプレートシステムであり、もうXNUMXつは日付と時刻のモジュールであり、多くの
もっと。 これらのものの独自のバージョンを書くことは通過儀礼ですが、どうぞ
Perlの世界で本当に公開する必要があるかどうかを慎重に検討してください。

しよう 〜へ do あまりに ずっと
モジュールは開発者のツールキットの一部になります。 それ自体では、
全体 ツールキット。 コードがモノリシックになるまで、機能を追加したくなります
モジュール式のビルディングブロックのセットではなく、システム。

不適切 ドキュメント
間違った聴衆のために書くという罠に陥らないでください。 あなたの主な聴衆は
モジュールを少なくともある程度理解している、十分な経験を積んだ開発者
モジュールをダウンロードしたばかりで、次のように使用を開始したいアプリケーションドメイン
できるだけ早く。

チュートリアル、エンドユーザードキュメント、研究論文、FAQなどは適切ではありません
モジュールのメインドキュメント。 これらを本当に書きたい場合は、サブとして含めてください。
「My::Module::Tutorial」や「My::Module::FAQ」などのドキュメントとリンクを提供する
メインドキュメントのセクションも参照してください。

onworks.netサービスを使用してオンラインでperlmodstyleを使用する