argra****@users*****
argra****@users*****
2017年 3月 28日 (火) 05:12:01 JST
Index: docs/perl/5.22.1/perlmodstyle.pod diff -u /dev/null docs/perl/5.22.1/perlmodstyle.pod:1.1 --- /dev/null Tue Mar 28 05:12:01 2017 +++ docs/perl/5.22.1/perlmodstyle.pod Tue Mar 28 05:12:01 2017 @@ -0,0 +1,1935 @@ + +=encoding euc-jp + +=head1 NAME + +=begin original + +perlmodstyle - Perl module style guide + +=end original + +perlmodstyle - Perl モジュールスタイルガイド + +=head1 INTRODUCTION + +=begin original + +This document attempts to describe the Perl Community's "best practice" +for writing Perl modules. It extends the recommendations found in +L<perlstyle> , which should be considered required reading +before reading this document. + +=end original + +このドキュメントは Perl コミュニティにおける +Perl モジュールを書くときの「ベストプラクティス」を +説明しています。 +これは L<perlstyle> にある推奨項目を拡張します; +L<perlstyle> はこのドキュメントに先立って目を通しておいてください。 + +=begin original + +While this document is intended to be useful to all module authors, it is +particularly aimed at authors who wish to publish their modules on CPAN. + +=end original + +このドキュメントは全てのモジュール作者に役立つように +意図していますが、CPAN にモジュールを公開しようと +している作者を特に意図しています。 + +=begin original + +The focus is on elements of style which are visible to the users of a +module, rather than those parts which are only seen by the module's +developers. However, many of the guidelines presented in this document +can be extrapolated and applied successfully to a module's internals. + +=end original + +焦点は、モジュール開発者の目にとまる点ではなく、 +モジュールのユーザの目にとまるスタイルの要素に置かれています。 +しかし、このドキュメントであげられているガイドラインの +多くはモジュールの内部にも推測、適用できるでしょう。 + +=begin original + +This document differs from L<perlnewmod> in that it is a style guide +rather than a tutorial on creating CPAN modules. It provides a +checklist against which modules can be compared to determine whether +they conform to best practice, without necessarily describing in detail +how to achieve this. + +=end original + +L<perlnewmod> は CPAN モジュールを作るためのチュートリアルであるのに対し、 +この文書はスタイルに関するガイドという点で異なっています。 +それはモジュールがベストプラクティスに沿っているかを +これを成し遂げる方法を詳細に記述する必要なしに +決定するために比較するためのチェックリストを +提供しています。 + +=begin original + +All the advice contained in this document has been gleaned from +extensive conversations with experienced CPAN authors and users. Every +piece of advice given here is the result of previous mistakes. This +information is here to help you avoid the same mistakes and the extra +work that would inevitably be required to fix them. + +=end original + +このドキュメントに含まれる全てのアドバイスは +経験に富んだ CPAN 作者及びユーザの広範囲にわたる +議論から少しずつ集められています。 +ここにあるアドバイスのどの欠片も以前の過ちの解決として +生まれました。 +この情報は同じ過ちを繰り返さないように、 +そして必然的にそれらを修正するという余計な作業が +必要とならないように、あなたを手助けするために +ここにあります。 + +=begin original + +The first section of this document provides an itemized checklist; +subsequent sections provide a more detailed discussion of the items on +the list. The final section, "Common Pitfalls", describes some of the +most popular mistakes made by CPAN authors. + +=end original + +このドキュメントの最初のセクションでは項目別のチェックリストを +提供します; その後のセクションではリストの各項目について +より詳しい説明を行います。 +そして最後のセクション、「よくある落とし穴」で CPAN 作者が +よくやってしまう、特にメジャーな失敗をいくつか説明します。 + +=head1 QUICK CHECKLIST + +(クイックチェックリスト) + +=begin original + +For more detail on each item in this checklist, see below. + +=end original + +このチェックリストにおける各項目の詳細は後のセクションを +参照してください。 + +=head2 Before you start + +(始める前に) + +=over 4 + +=item * + +=begin original + +Don't re-invent the wheel + +=end original + +車輪の再発明をしない + +=item * + +=begin original + +Patch, extend or subclass an existing module where possible + +=end original + +可能であるのなら既存のモジュールにパッチ、拡張、 +サブクラス化を行う + +=item * + +=begin original + +Do one thing and do it well + +=end original + +一つのことをうまくやる + +=item * + +=begin original + +Choose an appropriate name + +=end original + +ふさわしい名前を選ぶ + +=item * + +=begin original + +Get feedback before publishing + +=end original + +公開する前にフィードバックを得る + +=back + +=head2 The API + +(API) + +=over 4 + +=item * + +=begin original + +API should be understandable by the average programmer + +=end original + +API は平均的なプログラマが理解できるようにするべき + +=item * + +=begin original + +Simple methods for simple tasks + +=end original + +簡単なタスクのための簡単なメソッドを + +=item * + +=begin original + +Separate functionality from output + +=end original + +機能を出力から分離する + +=item * + +=begin original + +Consistent naming of subroutines or methods + +=end original + +関数やメソッドには一貫性のある名前を付ける + +=item * + +=begin original + +Use named parameters (a hash or hashref) when there are more than two +parameters + +=end original + +二つ以上の引数ををとるのなら +名前付きの引数(ハッシュまたはハッシュリファレンス)を使う + +=back + +=head2 Stability + +(安定性) + +=over 4 + +=item * + +=begin original + +Ensure your module works under C<use strict> and C<-w> + +=end original + +C<use strict> 及び C<-w> の環境下で動作することを +保証する + +=item * + +=begin original + +Stable modules should maintain backwards compatibility + +=end original + +安定したモジュールは後方互換性を維持するべき + +=back + +=head2 Documentation + +(ドキュメンテーション) + +=over 4 + +=item * + +=begin original + +Write documentation in POD + +=end original + +文書を POD 形式で書く + +=item * + +=begin original + +Document purpose, scope and target applications + +=end original + +目的、範囲、及び対象となるアプリケーションを記述する + +=item * + +=begin original + +Document each publically accessible method or subroutine, including params and return values + +=end original + +個々の公開されているアクセスメソッドまたは関数を、 +引数及び返り値も含めて記述する + +=item * + +=begin original + +Give examples of use in your documentation + +=end original + +文書に使い方を例示する + +=item * + +=begin original + +Provide a README file and perhaps also release notes, changelog, etc + +=end original + +README ファイルを提供する; またできればリリースノート、更新履歴も + +=item * + +=begin original + +Provide links to further information (URL, email) + +=end original + +さらなる情報へのリンク(URL, email)を提供する + +=back + +=head2 Release considerations + +(リリース時に確認すること) + +=over 4 + +=item * + +=begin original + +Specify pre-requisites in Makefile.PL or Build.PL + +=end original + +Makefile.PL または Build.PL に依存(pre-requisites)を記述する + +=item * + +=begin original + +Specify Perl version requirements with C<use> + +=end original + +動作に必要な Perl のバージョンを C<use> で記述する + +=item * + +=begin original + +Include tests with your module + +=end original + +モジュールにはテストを含める + +=item * + +=begin original + +Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme) + +=end original + +バージョン番号の採番には一般的で矛盾の起きない形式を選ぶ +(Perl モジュールでは一般的に X.YY が使われている) + +=item * + +=begin original + +Increment the version number for every change, no matter how small + +=end original + +たとえそれがどんなに小さな変更であっても、変更毎にバージョン番号を増やす + +=item * + +=begin original + +Package the module using "make dist" + +=end original + +モジュールのパッケージングには "make dist" を使う + +=item * + +=begin original + +Choose an appropriate license (GPL/Artistic is a good default) + +=end original + +適切なライセンスを選ぶ (GPL/Artistic はよいデフォルトです) + +=back + +=head1 BEFORE YOU START WRITING A MODULE + +(モジュールを書き始める前に) + +=begin original + +Try not to launch headlong into developing your module without spending +some time thinking first. A little forethought may save you a vast +amount of effort later on. + +=end original + +最初に少し考える時間を取らずにモジュール開発に取りかかろうとしないで +ください。 +予め少し考えておくことで、後での多くの苦労を防げます。 + +=head2 Has it been done before? + +(以前作られていなかった?) + +=begin original + +You may not even need to write the module. Check whether it's already +been done in Perl, and avoid re-inventing the wheel unless you have a +good reason. + +=end original + +そもそもモジュールを書く必要がないかもしれません。 +既に Perl で行われているかどうかを調べて、よい理由がない限り +車輪の再発明は避けてください。 + +=begin original + +Good places to look for pre-existing modules include +L<http://search.cpan.org/> and L<https://metacpan.org> +and asking on C<modul****@perl*****> +(L<http://lists.perl.org/list/module-authors.html>). + +=end original + +既にあるモジュールを探すのによい場所は、 +L<http://search.cpan.org/> および L<https://metacpan.org> と、 +C<modul****@perl*****> +(L<http://lists.perl.org/list/module-authors.html>) に聞くことです。 + +=begin original + +If an existing module B<almost> does what you want, consider writing a +patch, writing a subclass, or otherwise extending the existing module +rather than rewriting it. + +=end original + +もし既にあるモジュールがやりたいことを B<ほとんど> しているなら、 +それを書き直すのではなく、パッチを作ったり、派生クラスを作ったり、 +あるいは既にあるモジュールを拡張するためのその他の手段を考慮してください。 + +=head2 Do one thing and do it well + +(一つのことをうまくやる) + +=begin original + +At the risk of stating the obvious, modules are intended to be modular. +A Perl developer should be able to use modules to put together the +building blocks of their application. However, it's important that the +blocks are the right shape, and that the developer shouldn't have to use +a big block when all they need is a small one. + +=end original + +当たり前のことを述べるという危険を冒しますが、モジュールはモジュール式で +あることを目的としています。 +Perl 開発者は、自身のアプリケーションの建築ブロックを寄せ集めるために +モジュールを使えるようにするべきです。 +しかし、ブロックが正しい形をしていて、開発者が小さいブロックが必要な +だけのときに大きいブロックを使う必要がないようにすることが重要です。 + +=begin original + +Your module should have a clearly defined scope which is no longer than +a single sentence. Can your module be broken down into a family of +related modules? + +=end original + +モジュールは、一文だけで表現できる明確に定義されたスコープを持つべきです。 +あなたのモジュールは関係するモジュール群に分割できませんか? + +=begin original + +Bad example: + +=end original + +悪い例: + +=begin original + +"FooBar.pm provides an implementation of the FOO protocol and the +related BAR standard." + +=end original + +「FooBar.pm は、FOO プロトコルと、関連する BAR 標準の実装を提供します。」 + +=begin original + +Good example: + +=end original + +良い例: + +=begin original + +"Foo.pm provides an implementation of the FOO protocol. Bar.pm +implements the related BAR protocol." + +=end original + +「Foo.pm は FOO プロトコルの実装を提供します。 +Bar.pm は関連する BAR プロトコルを実装します。」 + +=begin original + +This means that if a developer only needs a module for the BAR standard, +they should not be forced to install libraries for FOO as well. + +=end original + +これは、もし開発者が BAR 標準のモジュールだけを必要としているなら、 +FOO ライブラリのインストールを強制されないということです。 + +=head2 What's in a name? + +(なんて名前?) + +=begin original + +Make sure you choose an appropriate name for your module early on. This +will help people find and remember your module, and make programming +with your module more intuitive. + +=end original + +前もって、モジュールのための適切な名前を選んでください。 +これは人々がモジュールを探したり覚えたりする助けになり、モジュールを +使ったプログラミングがより直観的になります。 + +=begin original + +When naming your module, consider the following: + +=end original + +モジュールに名前を付けるときには、以下のことを考慮してください: + +=over 4 + +=item * + +=begin original + +Be descriptive (i.e. accurately describes the purpose of the module). + +=end original + +説明的にする (モジュールの目的を正確に表現する)。 + +=item * + +=begin original + +Be consistent with existing modules. + +=end original + +すでにあるモジュールと一貫性をもつ。 + +=item * + +=begin original + +Reflect the functionality of the module, not the implementation. + +=end original + +モジュールの実装ではなく、モジュールの機能を反映させる。 + +=item * + +=begin original + +Avoid starting a new top-level hierarchy, especially if a suitable +hierarchy already exists under which you could place your module. + +=end original + +新しいトップレベル階層を作るのを避ける(特にモジュールを置くのに +適切な階層がすでにある場合は)。 + +=back + +=head2 Get feedback before publishing + +(公開する前にフィードバックを得る) + +=begin original + +If you have never uploaded a module to CPAN before (and even if you have), +you are strongly encouraged to get feedback on L<PrePAN|http://prepan.org>. +PrePAN is a site dedicated to discussing ideas for CPAN modules with other +Perl developers and is a great resource for new (and experienced) Perl +developers. + +=end original + +もし過去に CPAN にモジュールをアップロードしたことがないなら(そしてたとえ +したことがあっても)、L<PrePAN|http://prepan.org> でフィードバックを +得ることが強く推奨されます。 +PrePAN は CPAN モジュールのアイデアを他の Perl 開発者と議論することに特化した +サイトで、新しい (そして経験のある) Perl 開発者にとって素晴らしい +リソースです。 + +=begin original + +You should also try to get feedback from people who are already familiar +with the module's application domain and the CPAN naming system. Authors +of similar modules, or modules with similar names, may be a good place to +start, as are community sites like L<Perl Monks|http://www.perlmonks.org>. + +=end original + +また、すでにモジュールのアプリケーションドメインと CPAN 命名システムに +親しんでいる人々からフィードバックを得ようとするべきです。 +同様なモジュールの作者や、似た名前のモジュールは始めるのに +いいところでしょう; また L<Perl Monks|http://www.perlmonks.org> のような +コミュニティサイトもよいです。 + +=head1 DESIGNING AND WRITING YOUR MODULE + +(モジュールの設計と作成) + +=begin original + +Considerations for module design and coding: + +=end original + +モジュールの設計とコーディングで考慮すること: + +=head2 To OO or not to OO? + +(OO か非 OO か?) + +=begin original + +Your module may be object oriented (OO) or not, or it may have both kinds +of interfaces available. There are pros and cons of each technique, which +should be considered when you design your API. + +=end original + +モジュールはオブジェクト指向 (OO) にするかしないか、あるいは両方の +インターフェースを持つようにもできます。 +それぞれの技術には、API を設計するときに検討するべき +メリットデメリットがあります。 + +=begin original + +In I<Perl Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.), +Damian Conway provides a list of criteria to use when deciding if OO is the +right fit for your problem: + +=end original + +I<Perl ベストプラクティス>(Perl Best Practices>) (2004 年、 +オライリーメディアによって出版)で、Damian Conway は OO が問題を解決するのに +向いているかを判断するときに使う基準の一覧を提供しています: + +=over 4 + +=item * + +=begin original + +The system being designed is large, or is likely to become large. + +=end original + +システムが大きかったり大きくなりそう。 + +=item * + +=begin original + +The data can be aggregated into obvious structures, especially if +there's a large amount of data in each aggregate. + +=end original + +データが、オブジェクトになるよくある構造に集約される; 特にそれぞれの集約が +大量のデータである。 + +=item * + +=begin original + +The various types of data aggregate form a natural hierarchy that +facilitates the use of inheritance and polymorphism. + +=end original + +データ形式が継承や多態性を容易にするような自然な階層を形成している。 + +=item * + +=begin original + +You have a piece of data on which many different operations are +applied. + +=end original + +様々な異なる操作が行われるデータがある。 + +=item * + +=begin original + +You need to perform the same general operations on related types of +data, but with slight variations depending on the specific type of data +the operations are applied to. + +=end original + +データの型に関係する同じ一般的な操作をする必要があるけれども、操作を +適用するデータの型によって少しずつ異なる。 + +=item * + +=begin original + +It's likely you'll have to add new data types later. + +=end original + +後で新しいデータ型を追加する必要がありそう。 + +=item * + +=begin original + +The typical interactions between pieces of data are best represented by +operators. + +=end original + +データとの典型的な相互作用が演算子によって最もよく表現される。 + +=item * + +=begin original + +The implementation of individual components of the system is likely to +change over time. + +=end original + +システムの個々の要素の実装が後でやがて変更になりそう。 + +=item * + +=begin original + +The system design is already object-oriented. + +=end original + +システム設計自身が既にオブジェクト指向である。 + +=item * + +=begin original + +Large numbers of other programmers will be using your code modules. + +=end original + +大量のクライアントコードがこのソフトウェアを使う (そして実装から変更を +分離しておくべき) とき + +=back + +=begin original + +Think carefully about whether OO is appropriate for your module. +Gratuitous object orientation results in complex APIs which are +difficult for the average module user to understand or use. + +=end original + +あなたのモジュールに OO が適切かどうかを慎重に考えてください。 +不必要なオブジェクト指向は、平均的なモジュール利用者が理解や使用するのが +困難な複雑な API となります。 + +=head2 Designing your API + +(API の設計) + +=begin original + +Your interfaces should be understandable by an average Perl programmer. +The following guidelines may help you judge whether your API is +sufficiently straightforward: + +=end original + +インターフェースは平均的な Perl プログラマが理解可能であるべきです。 +以下のガイドラインは、API が充分に簡単かどうかを判断する手助けに +なるでしょう: + +=over 4 + +=item Write simple routines to do simple things. + +(単純なことをする単純なルーチンを書く。) + +=begin original + +It's better to have numerous simple routines than a few monolithic ones. +If your routine changes its behaviour significantly based on its +arguments, it's a sign that you should have two (or more) separate +routines. + +=end original + +少量の巨大なルーチンよりも、たくさんの単純なルーチンの方がよいです。 +ルーチンが引数によって大きく振る舞いを変えるなら、複数のルーチンに +分割するべきと言うサインです。 + +=item Separate functionality from output. + +(機能を出力から分離する。) + +=begin original + +Return your results in the most generic form possible and allow the user +to choose how to use them. The most generic form possible is usually a +Perl data structure which can then be used to generate a text report, +HTML, XML, a database query, or whatever else your users require. + +=end original + +結果は出来るだけ一般的な形式で返して、ユーザがそれをどのように使うかを +選択できるようにします。 +最も一般的な形式とは、おそらく後でテキストレポート、HTML、XML、 +データベースクエリ、あるいはユーザが求めるもの何でも生成できる +Perl データ構造です。 + +=begin original + +If your routine iterates through some kind of list (such as a list of +files, or records in a database) you may consider providing a callback +so that users can manipulate each element of the list in turn. +File::Find provides an example of this with its +C<find(\&wanted, $dir)> syntax. + +=end original + +あなたのルーチンがある種のリスト(ファイルのリスト、データベースの +レコードなど)に対して反復するなら、ユーザがリストのそれぞれの要素を +操作できるようなコールバックを提供することを考慮してください。 +File::Find は C<find(\&wanted, $dir)> という文法で、この場合の例を +提供しています。 + +=item Provide sensible shortcuts and defaults. + +(実用的なショートカットやデフォルトを提供する。) + +=begin original + +Don't require every module user to jump through the same hoops to achieve a +simple result. You can always include optional parameters or routines for +more complex or non-standard behaviour. If most of your users have to +type a few almost identical lines of code when they start using your +module, it's a sign that you should have made that behaviour a default. +Another good indicator that you should use defaults is if most of your +users call your routines with the same arguments. + +=end original + +単純な結果を得るために全てのモジュールユーザに同じ輪をくぐることを +要求しないようにしてください。 +より複雑だったり標準でない振る舞いのためには、常にオプションの引数や +ルーチンを用意して管浅い。 +もしほとんどのユーザがモジュールを使い始めるときにほとんど同じ +数行のコードを書く必要があるなら、それはその振る舞いをデフォルトに +するべきというサインです。 +デフォルトを使うべきというもう一つの指標は、ユーザのほとんどが同じ引数で +ルーチンを呼び出すときです。 + +=item Naming conventions + +(命名規則) + +=begin original + +Your naming should be consistent. For instance, it's better to have: + +=end original + +命名は一貫性を持たせるべきです。 +例えば、以下のものは: + + display_day(); + display_week(); + display_year(); + +=begin original + +than + +=end original + +以下のものよりよいです: + + display_day(); + week_display(); + show_year(); + +=begin original + +This applies equally to method names, parameter names, and anything else +which is visible to the user (and most things that aren't!) + +=end original + +これはメソッド名、引数名、その他ユーザに見えるもの何にでも +(そして見えない物のほとんどにも!)適用されます。 + +=item Parameter passing + +(引数の渡し方) + +=begin original + +Use named parameters. It's easier to use a hash like this: + +=end original + +名前付き引数を使いましょう。 +これは以下のようにハッシュを使えば: + + $obj->do_something( + name => "wibble", + type => "text", + size => 1024, + ); + +=begin original + +... than to have a long list of unnamed parameters like this: + +=end original + +…以下のように名前のない引数の長いリストより簡単です: + + $obj->do_something("wibble", "text", 1024); + +=begin original + +While the list of arguments might work fine for one, two or even three +arguments, any more arguments become hard for the module user to +remember, and hard for the module author to manage. If you want to add +a new parameter you will have to add it to the end of the list for +backward compatibility, and this will probably make your list order +unintuitive. Also, if many elements may be undefined you may see the +following unattractive method calls: + +=end original + +引数のリストは 1 引数、2 引数、そして 3 引数でもうまく動作するでしょうが、 +それ以上になるとモジュールユーザが覚えるのが難しくなり、モジュール +作者が管理するのも難しくなります。 +新しい引数を追加したいときは、後方互換性のためにリストの最後に追加する +必要があり、そしてこれによっておそらくリストの順序が直観的では +なくなるでしょう。 +また、多くの要素が未定義の場合、以下のような美しくないメソッド呼び出しを +見ることになるでしょう: + + $obj->do_something(undef, undef, undef, undef, undef, 1024); + +=begin original + +Provide sensible defaults for parameters which have them. Don't make +your users specify parameters which will almost always be the same. + +=end original + +引数に、意味のあるデフォルトがあるならそれをデフォルトにしましょう。 +ユーザーに、毎回ほとんど同じような引数を指定させてはいけません。 + +=begin original + +The issue of whether to pass the arguments in a hash or a hashref is +largely a matter of personal style. + +=end original + +引数をハッシュで渡すかハッシュリファレンスで渡すかの問題は主に個人的な +スタイルの問題です。 + +=begin original + +The use of hash keys starting with a hyphen (C<-name>) or entirely in +upper case (C<NAME>) is a relic of older versions of Perl in which +ordinary lower case strings were not handled correctly by the C<=E<gt>> +operator. While some modules retain uppercase or hyphenated argument +keys for historical reasons or as a matter of personal style, most new +modules should use simple lower case keys. Whatever you choose, be +consistent! + +=end original + +ハイフンで始まるハッシュキー (C<-name>) や全て大文字のハッシュキー +(C<NAME>) は、普通の小文字の文字列が C<=E<gt>> 演算子で扱えなかった +古いバージョンの Perl の遺物です。 +一部のモジュールでは歴史的な理由や個人的なスタイルの問題で大文字や +ハイフン付きのキーのままですが、ほとんどの新しいモジュールは単純な +小文字のキーを使うべきです。 +どちらを選ぶにせよ、一貫性を持ちましょう! + +=back + +=head2 Strictness and warnings + +(strict と warnings) + +=begin original + +Your module should run successfully under the strict pragma and should +run without generating any warnings. Your module should also handle +taint-checking where appropriate, though this can cause difficulties in +many cases. + +=end original + +モジュールは stirct プラグマ付きでも正しく動作し、一切の警告なしで +動作するべきです。 +また、適切な場所では汚染チェックも扱うべきですが、これは多くの場合で困難を +伴います。 + +=head2 Backwards compatibility + +(後方互換性) + +=begin original + +Modules which are "stable" should not break backwards compatibility +without at least a long transition phase and a major change in version +number. + +=end original + +「安定版の」モジュールは、少なくとも長い移行フェーズとバージョン番号の +メジャー番号の変更することなく、後方互換性を壊すべきではありません。 + +=head2 Error handling and messages + +(エラーハンドリングとメッセージ) + +=begin original + +When your module encounters an error it should do one or more of: + +=end original + +モジュールがエラーに遭遇した場合、以下の一つあるいは複数を行うべきです: + +=over 4 + +=item * + +=begin original + +Return an undefined value. + +=end original + +未定義値を返す。 + +=item * + +=begin original + +set C<$Module::errstr> or similar (C<errstr> is a common name used by +DBI and other popular modules; if you choose something else, be sure to +document it clearly). + +=end original + +C<$Module::errstr> あるいは同様のものを設定する (C<errstr> は DBI および +その他の有名なモジュールで使われている一般的な名前です; もし他のものを +選んだなら、それを明確に文書化しておきましょう)。 + +=item * + +=begin original + +C<warn()> or C<carp()> a message to STDERR. + +=end original + +C<warn()> や C<carp()> を使ってメッセージを STDERR に出力する。 + +=item * + +=begin original + +C<croak()> only when your module absolutely cannot figure out what to +do. (C<croak()> is a better version of C<die()> for use within +modules, which reports its errors from the perspective of the caller. +See L<Carp> for details of C<croak()>, C<carp()> and other useful +routines.) + +=end original + +C<croak()> は、あなたのモジュールが何をすればいいのか全く分からないときにのみ +使います。 +(C<croak()> はモジュール内で使うための C<die()> の改良版で、 +エラーを呼び出し元の観点から報告します。 +C<croak()>, C<carp()> およびその他の便利なルーチンについては +L<Carp> を参照してください。) + +=item * + +=begin original + +As an alternative to the above, you may prefer to throw exceptions using +the Error module. + +=end original + +上述の代替案として、Error モジュールを使って例外を投げる方を +好むかもしれません。 + +=back + +=begin original + +Configurable error handling can be very useful to your users. Consider +offering a choice of levels for warning and debug messages, an option to +send messages to a separate file, a way to specify an error-handling +routine, or other such features. Be sure to default all these options +to the commonest use. + +=end original + +設定可能なエラー処理はユーザーにとってとても便利です。 +警告やデバッグメッセージのレベルの選択、メッセージの別のファイルへの書き出し、 +エラー処理ルーチンの指定方法、あるいはその他の同様の機能の提供を +考慮してください。 +これらのオプション全てのデフォルトは最も一般的な使用法に設定してください。 + +=head1 DOCUMENTING YOUR MODULE + +(モジュールを文書化する) + +=head2 POD + +=begin original + +Your module should include documentation aimed at Perl developers. +You should use Perl's "plain old documentation" (POD) for your general +technical documentation, though you may wish to write additional +documentation (white papers, tutorials, etc) in some other format. +You need to cover the following subjects: + +=end original + +モジュールは Perl の開発者向けの文書を含めるべきです。 +一般的な技術文書に対しては Perl の "plain old documentation" (POD) を +使うべきですが、追加の文書 (ホワイトペーパー、チュートリアルなど) は +その他のフォーマットで書きたいかもしれません。 +以下のような主題に対応する必要があります: + +=over 4 + +=item * + +=begin original + +A synopsis of the common uses of the module + +=end original + +モジュールの一般的な使い方の概要 + +=item * + +=begin original + +The purpose, scope and target applications of your module + +=end original + +モジュールの目的、スコープ、対象アプリケーション + +=item * + +=begin original + +Use of each publically accessible method or subroutine, including +parameters and return values + +=end original + +(引数と返り値を含む) 公開されているメソッドやサブルーチンの使用法 + +=item * + +=begin original + +Examples of use + +=end original + +使用例 + +=item * + +=begin original + +Sources of further information + +=end original + +さらなる情報の情報源 + +=item * + +=begin original + +A contact email address for the author/maintainer + +=end original + +作者/メンテナへ連絡するための email アドレス + +=back + +=begin original + +The level of detail in Perl module documentation generally goes from +less detailed to more detailed. Your SYNOPSIS section should contain a +minimal example of use (perhaps as little as one line of code; skip the +unusual use cases or anything not needed by most users); the +DESCRIPTION should describe your module in broad terms, generally in +just a few paragraphs; more detail of the module's routines or methods, +lengthy code examples, or other in-depth material should be given in +subsequent sections. + +=end original + +Perl モジュール文書の詳細度は、一般的に概略から詳細へという順序に +なっています。 +SYNOPSIS 節には使うための最小限の例を含むべきです +(おそらくは一行でしょう; 一般的でない使い方やほとんどのユーザーにとって +必要でないものは省略します); +DESCRIPTION はモジュールを広義で記述し、一般的には単に数段落です; +モジュールのルーチンやメソッドに関する更なる詳細、長いコード例、その他の +より深い内容は引き続く節に書くべきです。 + +=begin original + +Ideally, someone who's slightly familiar with your module should be able +to refresh their memory without hitting "page down". As your reader +continues through the document, they should receive a progressively +greater amount of knowledge. + +=end original + +理想的には、モジュールに対して少しなじみのあるユーザーなら "page down" キーを +押すことなく記憶を思い出せるようにするべきです。 +読者が文書を読み進めるにつれて、徐々に多くの量の知識を受け取ります。 + +=begin original + +The recommended order of sections in Perl module documentation is: + +=end original + +推奨する Perl モジュール文書の章の順序は: + +=over 4 + +=item * + +NAME + +=item * + +SYNOPSIS + +=item * + +DESCRIPTION + +=item * + +=begin original + +One or more sections or subsections giving greater detail of available +methods and routines and any other relevant information. + +=end original + +利用可能なメソッドやルーチンのより詳細と、その他の関係する情報のための +一つまたは複数の節。 + +=item * + +=begin original + +BUGS/CAVEATS/etc + +=end original + +BUGS/CAVEATS など + +=item * + +AUTHOR + +=item * + +SEE ALSO + +=item * + +=begin original + +COPYRIGHT and LICENSE + +=end original + +COPYRIGHT と LICENSE + +=back + +=begin original + +Keep your documentation near the code it documents ("inline" +documentation). Include POD for a given method right above that +method's subroutine. This makes it easier to keep the documentation up +to date, and avoids having to document each piece of code twice (once in +POD and once in comments). + +=end original + +文書は、記述しているコードの近くになるように(「インライン」文書) +維持してください。 +メソッドのための POD はメソッドのサブルーチンの直前に書いてください。 +これにより文書を最新に保つのが容易になり、一つのコードに対して 2 箇所 +(POD とコメント) に書く必要がなくなります。 + +=head2 README, INSTALL, release notes, changelogs + +(README, INSTALL, リリースノート, changelogs) + +=begin original + +Your module should also include a README file describing the module and +giving pointers to further information (website, author email). + +=end original + +モジュールには、モジュールの説明と、さらなる情報へのポインタ (ウェブサイト、 +作者への email) を記述した README ファイルも含めるべきです。 + +=begin original + +An INSTALL file should be included, and should contain simple installation +instructions. When using ExtUtils::MakeMaker this will usually be: + +=end original + +INSTALL ファイルを含めて、そこに簡単なインストール手順を記述するべきです。 +ExtUtils::MakeMaker を使っているなら、これは普通は以下のようになります: + +=over 4 + +=item perl Makefile.PL + +=item make + +=item make test + +=item make install + +=back + +=begin original + +When using Module::Build, this will usually be: + +=end original + +Module::Build を使っているなら、これは普通は以下のようになります: + +=over 4 + +=item perl Build.PL + +=item perl Build + +=item perl Build test + +=item perl Build install + +=back + +=begin original + +Release notes or changelogs should be produced for each release of your +software describing user-visible changes to your module, in terms +relevant to the user. + +=end original + +リリースノートまたは changelogs は、ユーザーからの観点でモジュールの +ユーザーから見える変更点を記述して、リリース毎に作成するべきです。 + +=begin original + +Unless you have good reasons for using some other format +(for example, a format used within your company), +the convention is to name your changelog file C<Changes>, +and to follow the simple format described in L<CPAN::Changes::Spec>. + +=end original + +他の形式を使う良い理由 (例えば、会社で使われている形式) がない限り、 +変更履歴ファイルは C<Changes> という名前にして、L<CPAN::Changes::Spec> に +ある単純な形式に従うのが慣習です。 + +=head1 RELEASE CONSIDERATIONS + +=head2 Version numbering + +(バージョン番号) + +=begin original + +Version numbers should indicate at least major and minor releases, and +possibly sub-minor releases. A major release is one in which most of +the functionality has changed, or in which major new functionality is +added. A minor release is one in which a small amount of functionality +has been added or changed. Sub-minor version numbers are usually used +for changes which do not affect functionality, such as documentation +patches. + +=end original + +バージョン番号は少なくともメジャーリリースとマイナーリリース、そして +場合により副マイナーリリースを示すべきです。 +メジャーリリースは、主な機能の変更や、あるいは主な新機能が +追加です。 +マイナーリリースは機能の一部の追加や修正です。 +副マイナーバージョン番号は普通、文書パッチのような機能に影響を与えない +変更に使われます。 + +=begin original + +The most common CPAN version numbering scheme looks like this: + +=end original + +最も一般的な CPAN のバージョン番号付け方式は次のようなものです: + + 1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32 + +=begin original + +A correct CPAN version number is a floating point number with at least +2 digits after the decimal. You can test whether it conforms to CPAN by +using + +=end original + +正しい CPAN バージョン番号は、小数点の後に少なくとも 2 桁の数字がある +浮動小数点数です。 +CPAN に準拠しているかどうかは以下のようにしてテストできます + + perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm' + +=begin original + +If you want to release a 'beta' or 'alpha' version of a module but +don't want CPAN.pm to list it as most recent use an '_' after the +regular version number followed by at least 2 digits, eg. 1.20_01. If +you do this, the following idiom is recommended: + +=end original + +「ベータ」あるいは「アルファ」バージョンのモジュールをリリースしたいけれども +CPAN.pm に最新版として扱ってほしくない場合、通常のバージョン番号の +後に '_' を使い、引き続いて最低 2 桁の数字を付けます; 例えば 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 + +=begin original + +With that trick MakeMaker will only read the first line and thus read +the underscore, while the perl interpreter will evaluate the $VERSION +and convert the string into a number. Later operations that treat +$VERSION as a number will then be able to do so without provoking a +warning about $VERSION not being a number. + +=end original + +この小技を使うと、MakeMaker は最初の行だけを読むので下線付きで読み、 +一方 perl インタプリタは $VERSION を eval して文字列を数値に変換します。 +これにより、後の操作で $VERSION を数値として扱うものがあっても +$VERSION が数値でないという警告が出なくなります。 + +=begin original + +Never release anything (even a one-word documentation patch) without +incrementing the number. Even a one-word documentation patch should +result in a change in version at the sub-minor level. + +=end original + +(たとえ 1 文字の文書パッチでも)バージョン番号を増やすことなく何かを +リリースしてはいけません。 +1 文字の文書パッチであっても副マイナー番号を変更するべきです。 + +=begin original + +Once picked, it is important to stick to your version scheme, without +reducing the number of digits. This is because "downstream" packagers, +such as the FreeBSD ports system, interpret the version numbers in +various ways. If you change the number of digits in your version scheme, +you can confuse these systems so they get the versions of your module +out of order, which is obviously bad. + +=end original + +一旦選択したら、数字の数を減らすことなく、そのバージョンスキームに +こだわることは重要です。 +これは、FreeBSD port システムのような「下流」パッケージ作成者は +バージョン番号を様々な方法で解釈するからです。 +バージョンスキームで数字の数を変えると、これらのシステムが混乱して、 +モジュールのバージョンの順番が間違ったことになるかもしれません; 明らかに +これは悪いことです。 + +=head2 Pre-requisites + +(依存) + +=begin original + +Module authors should carefully consider whether to rely on other +modules, and which modules to rely on. + +=end original + +モジュール作者は、他のモジュールに依存するかどうか、どのモジュールに +依存するかについて注意深く考慮するべきです。 + +=begin original + +Most importantly, choose modules which are as stable as possible. In +order of preference: + +=end original + +もっとも重要なこととして、できるだけ安定しているモジュールを選んでください。 +優先順位としては: + +=over 4 + +=item * + +=begin original + +Core Perl modules + +=end original + +コア Perl モジュール + +=item * + +=begin original + +Stable CPAN modules + +=end original + +安定している CPAN モジュール + +=item * + +=begin original + +Unstable CPAN modules + +=end original + +不安定な CPAN モジュール + +=item * + +=begin original + +Modules not available from CPAN + +=end original + +CPAN から利用できないモジュール + +=back + +=begin original + +Specify version requirements for other Perl modules in the +pre-requisites in your Makefile.PL or Build.PL. + +=end original + +Makefile.PL か Build.PL の pre-requisites に、他の Perl モジュールの +必要バージョンを指定します。 + +=begin original + +Be sure to specify Perl version requirements both in Makefile.PL or +Build.PL and with C<require 5.6.1> or similar. See the section on +C<use VERSION> of L<perlfunc/require> for details. + +=end original + +Makefile.PL や Build.PL と、C<require 5.6.1> のような形の両方で、 +Perl の必要バージョンを指定します。 +詳しくは L<perlfunc/require> の C<use VERSION> の節を参照してください。 + +=head2 Testing + +(テスト) + +=begin original + +All modules should be tested before distribution (using "make disttest"), +and the tests should also be available to people installing the modules +(using "make test"). +For Module::Build you would use the C<make test> equivalent C<perl Build test>. + +=end original + +全てのモジュールは配布する前に ("make disttest" を使って) +テストされるべきですし、テストはモジュールをインストールしようとしている +人々によっても ("make test" を使って) 実行可能であるべきです。 +Module::Build の場合は C<make test> の等価物である C<perl Build test> を +使います。 + +=begin original + +The importance of these tests is proportional to the alleged stability of a +module. A module which purports to be +stable or which hopes to achieve wide +use should adhere to as strict a testing regime as possible. + +=end original + +これらのテストの重要性はモジュールの安定性に比例します。 +安定していると表明したり、広く使われることを望むモジュールは、できるだけ +厳密なテスト体制に固執するべきです。 + +=begin original + +Useful modules to help you write tests (with minimum impact on your +development process or your time) include Test::Simple, Carp::Assert +and Test::Inline. +For more sophisticated test suites there are Test::More and Test::MockObject. + +=end original + +(開発プロセスや時間に与える影響を最小限にするように) テストを書くのを助ける +モジュールには Test::Simple, Carp::Assert, Test::Inline などがあります。 +さらに洗練されたテストスイートは Test::More と Test::MockObject です。 + +=head2 Packaging + +(パッケージング) + +=begin original + +Modules should be packaged using one of the standard packaging tools. +Currently you have the choice between ExtUtils::MakeMaker and the +more platform independent Module::Build, allowing modules to be installed in a +consistent manner. +When using ExtUtils::MakeMaker, you can use "make dist" to create your +package. Tools exist to help you to build your module in a +MakeMaker-friendly style. These include ExtUtils::ModuleMaker and h2xs. +See also L<perlnewmod>. + +=end original + +モジュールは標準パッケージツールの一つを使ってパッケージ化されるべきです。 +現在のところ ExtUtils::MakeMaker と、よりプラットフォーム非依存で +モジュールを一貫した方法でインストール出来る Module::Build という +選択肢があります。 +ExtUtils::MakeMaker を使う場合、パッケージを作るには "make dist" を使います。 +MakeMaker に親和性のある形でモジュールのビルドを助けるツールが存在します。 +ExtUtils::ModuleMaker や h2xs です。 +L<perlnewmod> も参照してください。 + +=head2 Licensing + +(ライセンス) + +=begin original + +Make sure that your module has a license, and that the full text of it +is included in the distribution (unless it's a common one and the terms +of the license don't require you to include it). + +=end original + +モジュールにはライセンスを付け、(そのライセンスが一般的なもので、 +そのライセンスがライセンスの全文を配布物に含めることを要求していないのでない +限り)、その全文を配布に含めるようにしてください。 + +=begin original + +If you don't know what license to use, dual licensing under the GPL +and Artistic licenses (the same as Perl itself) is a good idea. +See L<perlgpl> and L<perlartistic>. + +=end original + +もしどのライセンスを使えばいいかわからない場合は、GPL と +Artistic licenses のデュアルライセンス (Perl 自身と同じ) にするというのが +いい考えです。 +L<perlgpl> と L<perlartistic> を参照してください。 + +=head1 COMMON PITFALLS + +(よくある落とし穴) + +=head2 Reinventing the wheel + +(車輪の再発明) + +=begin original + +There are certain application spaces which are already very, very well +served by CPAN. One example is templating systems, another is date and +time modules, and there are many more. While it is a rite of passage to +write your own version of these things, please consider carefully +whether the Perl world really needs you to publish it. + +=end original + +CPAN によって提供されている、すでにとてもとてもうまくいっている +アプリケーション分野もあります。 +例としてはテンプレートシステムや日付と時間のためのモジュールであり、 +その他にもたくさんあります。 +これらのものの自分専用版を書くというのは通過儀礼ではありますが、 +あなたがそれを公開することを Perl の世界が本当に必要としているかどうかを +慎重に検討してください。 + +=head2 Trying to do too much + +(やりすぎ) + +=begin original + +Your module will be part of a developer's toolkit. It will not, in +itself, form the B<entire> toolkit. It's tempting to add extra features +until your code is a monolithic system rather than a set of modular +building blocks. + +=end original + +あなたのモジュールは開発者のツールキットの一部です。 +ツールキット B<全体> ではありません。 +これはあなたのコードをモジュール化された建築ブロックではなく一枚岩のシステムに +なるまで余分な機能を追加しようとする誘惑です。 + +=head2 Inappropriate documentation + +(不適切な文書) + +=begin original + +Don't fall into the trap of writing for the wrong audience. Your +primary audience is a reasonably experienced developer with at least +a moderate understanding of your module's application domain, who's just +downloaded your module and wants to start using it as quickly as possible. + +=end original + +間違った読者に向けて書くという罠に陥らないでください。 +主な読者は、少なくともモジュールの適用分野についてある程度の理解のある +適度に経験を積んだ開発者で、単にモジュールをダウンロードして、できるだけ +早く使い始めたいと思っている人々です。 + +=begin original + +Tutorials, end-user documentation, research papers, FAQs etc are not +appropriate in a module's main documentation. If you really want to +write these, include them as sub-documents such as C<My::Module::Tutorial> or +C<My::Module::FAQ> and provide a link in the SEE ALSO section of the +main documentation. + +=end original + +チュートリアル、エンドユーザー向け文書、研究論文、FAQ などはモジュールの +主文書としては不適切です。 +どうしてもこれらのものを書きたいなら、C<My::Module::Tutorial> や +C<My::Module::FAQ> のような副文書として含めて、主文書の SEE ALSO 節に +リンクをつけてください。 + +=head1 SEE ALSO + +=over 4 + +=item L<perlstyle> + +=begin original + +General Perl style guide + +=end original + +一般的な Perl スタイルガイド + +=item L<perlnewmod> + +=begin original + +How to create a new module + +=end original + +新しいモジュールの作り方 + +=item L<perlpod> + +=begin original + +POD documentation + +=end original + +POD 文書 + +=item L<podchecker> + +=begin original + +Verifies your POD's correctness + +=end original + +POD の正しさを検証する + +=item Packaging Tools + +(パッケージングツール) + +L<ExtUtils::MakeMaker>, L<Module::Build> + +=item Testing tools + +(テストツール) + +L<Test::Simple>, L<Test::Inline>, L<Carp::Assert>, L<Test::More>, L<Test::MockObject> + +=item http://pause.perl.org/ + +=begin original + +Perl Authors Upload Server. Contains links to information for module +authors. + +=end original + +Perl Authors Upload Server。 +モジュール作者のための情報へのリンクがあります。 + +=item Any good book on software engineering + +(ソフトウェア工学に関する良い本はなんでも) + +=back + +=head1 AUTHOR + +Kirrily "Skud" Robert <skud****@cpan*****> + +=begin meta + +Translate: 山科 氷魚 (YAMASHINA Hio) <hio****@hio*****> (5.10.0) +Update: SHIRAKATA Kentaro <argra****@ub32*****> (5.10.1-) +Status: completed + +=end meta +
