argra****@users*****
argra****@users*****
2011年 7月 3日 (日) 13:39:03 JST
Index: docs/perl/5.10.1/perlmodstyle.pod diff -u docs/perl/5.10.1/perlmodstyle.pod:1.4 docs/perl/5.10.1/perlmodstyle.pod:1.5 --- docs/perl/5.10.1/perlmodstyle.pod:1.4 Sat May 7 04:15:22 2011 +++ docs/perl/5.10.1/perlmodstyle.pod Sun Jul 3 13:39:03 2011 @@ -63,9 +63,8 @@ =end original -このドキュメントは L<perlnewmod> とは、それが CPAN モジュールを -作るためのチュートリアルであるのに対し、 -こちらはスタイルに関するガイドという点で異なっています。 +L<perlnewmod> は CPAN モジュールを作るためのチュートリアルであるのに対し、 +この文書はスタイルに関するガイドという点で異なっています。 それはモジュールがベストプラクティスに沿っているかを これを成し遂げる方法を詳細に記述する必要なしに 決定するために比較するためのチェックリストを @@ -292,7 +291,7 @@ =end original 個々の公開されているアクセスメソッドまたは関数を、 -パラメータ及び返り値も含めて記述する +引数及び返り値も含めて記述する =item * @@ -456,7 +455,7 @@ =end original もし既にあるモジュールがやりたいことを B<ほとんど> しているなら、 -それを書き直すのではなく、パッチの作ったり、派生クラスの作ったり、 +それを書き直すのではなく、パッチを作ったり、派生クラスを作ったり、 あるいは既にあるモジュールを拡張するためのその他の手段を考慮してください。 =head2 Do one thing and do it well @@ -473,12 +472,12 @@ =end 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. -(TBT) +当たり前のことを述べるという危険を冒しますが、モジュールはモジュール式で +あることを目的としています。 +Perl 開発者は、自身のアプリケーションの建築ブロックを寄せ集めるために +モジュールを使えるようにするべきです。 +しかし、ブロックが正しい形をしていて、開発者が小さいブロックが必要な +だけのときに大きいブロックを使う必要がないようにすることが重要です。 =begin original @@ -488,10 +487,8 @@ =end 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? -(TBT) +モジュールは、一文だけで表現できる明確に定義されたスコープを持つべきです。 +あなたのモジュールは関係するモジュール群に分割できませんか? =begin original @@ -535,9 +532,8 @@ =end 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. -(TBT) +これは、もし開発者が BAR 標準のモジュールだけを必要としているなら、 +FOO ライブラリのインストールを強制されないということです。 =head2 What's in a name? @@ -619,12 +615,12 @@ =end original -You should contact modul****@perl***** to ask them about your module name -before publishing your module. You should also try to ask 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. -(TBT) +モジュールを出版する前に、モジュール名について訊ねるために +modu****@perl***** に連絡するべきです。 +また、すでにモジュールのアプリケーションドメインと CPAN 命名システムに +親しんでいる人々に尋ねてみるべきです。 +同様なモジュールの作者や、似た名前のモジュールは始めるのに +いいところでしょう。 =head1 DESIGNING AND WRITING YOUR MODULE @@ -683,8 +679,7 @@ =end original -When the data is aggregated in obvious structures that will become objects -(TBT) +データが、オブジェクトになるよくある構造に集約されるとき =item * @@ -694,8 +689,7 @@ =end original -When the types of data form a natural hierarchy that can make use of inheritance -(TBT) +データ形式が継承して利用できる自然な階層を形成しているとき =item * @@ -706,9 +700,8 @@ =end original -When operations on data vary according to data type (making -polymorphic invocation of methods feasible) -(TBT) +データの操作がデータ型によってさまざまなとき(多態性のあるメソッド起動が +有効なとき) =item * @@ -719,9 +712,8 @@ =end original -When it is likely that new data types may be later introduced -into the system, and will need to be handled by existing code -(TBT) +新しいデータ型が後でシステムに導入されそうで、すでにあるコードで扱う +必要があるとき =item * @@ -732,9 +724,7 @@ =end original -When interactions between data are best represented by -overloaded operators -(TBT) +データとの相互作用がオーバーロードされた演算子によって最もよく表現されるとき =item * @@ -745,9 +735,8 @@ =end original -When the implementation of system components is likely to -change over time (and hence should be encapsulated) -(TBT) +システムの要素の実装が後でやがて変更になりそうな (従ってカプセル化するべき) +とき =item * @@ -757,8 +746,7 @@ =end original -When the system design is itself object-oriented -(TBT) +システム設計自身がオブジェクト指向のとき =item * @@ -769,9 +757,8 @@ =end original -When large amounts of client code will use the software (and -should be insulated from changes in its implementation) -(TBT) +大量のクライアントコードがこのソフトウェアを使う (そして実装から変更を +分離しておくべき) とき =item * @@ -782,9 +769,7 @@ =end original -When many separate operations will need to be applied to the -same set of data -(TBT) +多くの別々の操作を同じデータ集合に適用する必要があるとき =back @@ -796,10 +781,9 @@ =end 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. -(TBT) +あなたのモジュールに OO が適切かどうかを慎重に考えてください。 +不必要なオブジェクト指向は、平均的なモジュール利用者が理解や使用するのが +困難な複雑な API となります。 =head2 Designing your API @@ -813,10 +797,9 @@ =end original -Your interfaces should be understandable by an average Perl programmer. -The following guidelines may help you judge whether your API is -sufficiently straightforward: -(TBT) +インターフェースは平均的な Perl プログラマが理解可能であるべきです。 +以下のガイドラインは、API が充分に簡単かどうかを判断する手助けに +なるでしょう: =over 4 @@ -833,11 +816,9 @@ =end 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. -(TBT) +少量の巨大なルーチンよりも、たくさんの単純なルーチンの方がよいです。 +ルーチンが引数によって大きく振る舞いを変えるなら、複数のルーチンに +分割するべきと言うサインです。 =item Separate functionality from output. @@ -852,11 +833,11 @@ =end 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. -(TBT) +結果は出来るだけ一般的な形式で返して、ユーザがそれをどのように使うかを +選択できるようにします。 +最も一般的な形式とは、おそらく後でテキストレポート、HTML、XML、 +データベースクエリ、あるいはユーザが求めるもの何でも生成できる +Perl データ構造です。 =begin original @@ -868,12 +849,11 @@ =end 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. -(TBT) +あなたのルーチンがある種のリスト(ファイルのリスト、データベースの +レコードなど)に対して反復するなら、ユーザがリストのそれぞれの要素を +操作できるようなコールバックを提供することを考慮してください。 +File::Find は C<find(\&wanted, $dir)> という文法で、この場合の例を +提供しています。 =item Provide sensible shortcuts and defaults. @@ -891,14 +871,15 @@ =end 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. -(TBT) +単純な結果を得るために全てのモジュールユーザに同じ輪をくぐることを +要求しないようにしてください。 +より複雑だったり標準でない振る舞いのためには、常にオプションの引数や +ルーチンを用意して管浅い。 +もしほとんどのユーザがモジュールを使い始めるときにほとんど同じ +数行のコードを書く必要があるなら、それはその振る舞いをデフォルトに +するべきというサインです。 +デフォルトを使うべきというもう一つの指標は、ユーザのほとんどが同じ引数で +ルーチンを呼び出すときです。 =item Naming conventions @@ -910,8 +891,8 @@ =end original -Your naming should be consistent. For instance, it's better to have: -(TBT) +命名は一貫性を持たせるべきです。 +例えば、以下のものは: display_day(); display_week(); @@ -923,8 +904,7 @@ =end original -than -(TBT) +以下のものよりよいです: display_day(); week_display(); @@ -937,13 +917,12 @@ =end original -This applies equally to method names, parameter names, and anything else -which is visible to the user (and most things that aren't!) -(TBT) +これはメソッド名、引数名、その他ユーザに見えるもの何にでも +(そして見えない物のほとんどにも!)適用されます。 =item Parameter passing -(パラメータの渡し方) +(引数の渡し方) =begin original @@ -952,7 +931,7 @@ =end original 名前付き引数を使いましょう。 -これは以下のようにハッシュを使えばより簡単です: +これは以下のようにハッシュを使えば: $obj->do_something( name => "wibble", @@ -966,8 +945,7 @@ =end original -... than to have a long list of unnamed parameters like this: -(TBT) +…以下のように名前のない引数の長いリストより簡単です: $obj->do_something("wibble", "text", 1024); @@ -983,14 +961,14 @@ =end 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: -(TBT) +引数のリストは 1 引数、2 引数、そして 3 引数でもうまく動作するでしょうが、 +それ以上になるとモジュールユーザが覚えるのが難しくなり、モジュール +作者が管理するのも難しくなります。 +新しい引数を追加したいときは、後方互換性のためにリストの最後に追加する +必要があり、そしてこれによっておそらくリストの順序が直観的では +なくなるでしょう。 +また、多くの要素が未定義の場合、以下のような美しくないメソッド呼び出しを +見ることになるでしょう: $obj->do_something(undef, undef, undef, undef, undef, undef, 1024); @@ -1001,9 +979,8 @@ =end original -Provide sensible defaults for parameters which have them. Don't make -your users specify parameters which will almost always be the same. -(TBT) +引数に、意味のあるデフォルトがあるならそれをデフォルトにしましょう。 +ユーザーに、毎回ほとんど同じような引数を指定させてはいけません。 =begin original @@ -1012,9 +989,8 @@ =end original -The issue of whether to pass the arguments in a hash or a hashref is -largely a matter of personal style. -(TBT) +引数をハッシュで渡すかハッシュリファレンスで渡すかの問題は主に個人的な +スタイルの問題です。 =begin original @@ -1028,14 +1004,13 @@ =end 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! -(TBT) +ハイフンで始まるハッシュキー (C<-name>) や全て大文字のハッシュキー +(C<NAME>) は、普通の小文字の文字列が C<=E<gt>> 演算子で扱えなかった +古いバージョンの Perl の遺物です。 +一部のモジュールでは歴史的な理由や個人的なスタイルの問題で大文字や +ハイフン付きのキーのままですが、ほとんどの新しいモジュールは単純な +小文字のキーを使うべきです。 +どちらを選ぶにせよ、一貫性を持ちましょう! =back @@ -1052,11 +1027,10 @@ =end 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. -(TBT) +モジュールは stirct プラグマ付きでも正しく動作し、一切の警告なしで +動作するべきです。 +また、適切な場所では汚染チェックも扱うべきですが、これは多くの場合で困難を +伴います。 =head2 Backwards compatibility @@ -1070,10 +1044,8 @@ =end original -Modules which are "stable" should not break backwards compatibility -without at least a long transition phase and a major change in version -number. -(TBT) +「安定版の」モジュールは、少なくとも長い移行フェーズとバージョン番号の +メジャー番号の変更することなく、後方互換性を壊すべきではありません。 =head2 Error handling and messages @@ -1109,10 +1081,9 @@ =end 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). -(TBT) +C<$Module::errstr> あるいは同様のものを設定する (C<errstr> は DBI および +その他の有名なモジュールで使われている一般的な名前です; もし他のものを +選んだなら、それを明確に文書化しておきましょう)。 =item * @@ -1136,12 +1107,12 @@ =end 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.) -(TBT) +C<croak()> は、あなたのモジュールが何をすればいいのか全く分からないときにのみ +使います。 +(C<croak()> はモジュール内で使うための C<die()> の改良版で、 +エラーを呼び出し元の観点から報告します。 +C<croak()>, C<carp()> およびその他の便利なルーチンについては +L<Carp> を参照してください。) =item * @@ -1152,9 +1123,8 @@ =end original -As an alternative to the above, you may prefer to throw exceptions using -the Error module. -(TBT) +上述の代替案として、Error モジュールを使って例外を投げる方を +好むかもしれません。 =back @@ -1168,12 +1138,11 @@ =end 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. -(TBT) +設定可能なエラー処理はユーザーにとってとても便利です +警告やデバッグメッセージのレベルの選択、メッセージの別のファイルへの書き出し、 +エラー処理ルーチンの指定方法、あるいはその他の同様の機能の提供を +考慮してください。 +これらのオプション全てのデフォルトは最も一般的な使用法に設定してください。 =head1 DOCUMENTING YOUR MODULE @@ -1191,12 +1160,11 @@ =end 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: -(TBT) +モジュールは Perl の開発者向けの文書を含めるべきです。 +一般的な技術文書に対しては Perl の "plain old documentation" (POD) を +使うべきですが、追加の文書 (ホワイトペーパー、チュートリアルなど) は +その他のフォーマットで書きたいかもしれません。 +以下のような主題に対応する必要があります: =over 4 @@ -1229,9 +1197,7 @@ =end original -Use of each publically accessible method or subroutine, including -parameters and return values -(TBT) +(引数と返り値を含む) 公開されているメソッドやサブルーチンの使用法 =item * @@ -1278,15 +1244,14 @@ =end 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. -(TBT) +Perl モジュール文書の詳細度は、一般的に概略から詳細へという順序に +なっています。 +SYNOPSIS 節には使うための最小限の例を含むべきです +(おそらくは一行でしょう; 一般的でない使い方やほとんどのユーザーにとって +必要でないものは省略します); +DESCRIPTION はモジュールを広義で記述し、一般的には単に数段落です; +モジュールのルーチンやメソッドに関する更なる詳細、長いコード例、その他の +より深い内容は引き続く節に書くべきです。 =begin original @@ -1297,11 +1262,9 @@ =end 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. -(TBT) +理想的には、モジュールに対して少しなじみのあるユーザーなら "page down" キーを +押すことなく記憶を思い出せるようにするべきです。 +読者が文書を読み進めるにつれて、徐々に多くの量の知識を受け取ります。 =begin original @@ -1334,9 +1297,8 @@ =end original -One or more sections or subsections giving greater detail of available -methods and routines and any other relevant information. -(TBT) +利用可能なメソッドやルーチンのより詳細と、その他の関係する情報のための +一つまたは複数の節。 =item * @@ -1378,12 +1340,11 @@ =end 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). -(TBT) +文書は、記述しているコードの近くになるように(「インライン」文書) +維持してください。 +メソッドのための POD はメソッドのサブルーチンの直前に書いてください。 +これにより文書を最新に保つのが容易になり、一つのコードに対して 2 箇所 +(POD とコメント) に書く必要がなくなります。 =head2 README, INSTALL, release notes, changelogs @@ -1396,9 +1357,8 @@ =end original -Your module should also include a README file describing the module and -giving pointers to further information (website, author email). -(TBT) +モジュールには、モジュールの説明と、さらなる情報へのポインタ (ウェブサイト、 +作者への email) を記述した README ファイルも含めるべきです。 =begin original @@ -1407,9 +1367,8 @@ =end original -An INSTALL file should be included, and should contain simple installation -instructions. When using ExtUtils::MakeMaker this will usually be: -(TBT) +INSTALL ファイルを含めて、そこに簡単なインストール手順を記述するべきです。 +ExtUtils::MakeMaker を使っているなら、これは普通は以下のようになります: =over 4 @@ -1429,7 +1388,7 @@ =end original -Module::Build を使うなら、これは普通は以下のようになります: +Module::Build を使っているなら、これは普通は以下のようになります: =over 4 @@ -1451,10 +1410,8 @@ =end 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. -(TBT) +リリースノートまたは changelogs は、ユーザーからの観点でモジュールの +ユーザーから見える変更点を記述して、リリース毎に作成するべきです。 =head1 RELEASE CONSIDERATIONS @@ -1476,13 +1433,11 @@ バージョン番号は少なくともメジャーリリースとマイナーリリース、そして 場合により副マイナーリリースを示すべきです。 -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. -(TBT) +メジャーリリースは、主な機能の変更や、あるいは主な新機能が +追加です。 +マイナーリリースは機能の一部の追加や修正です。 +副マイナーバージョン番号は普通、文書パッチのような機能に影響を与えない +変更に使われます。 =begin original @@ -1517,11 +1472,10 @@ =end 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: -(TBT) +「ベータ」あるいは「アルファ」バージョンのモジュールをリリースしたいけれども +CPAN.pm に最新版として扱ってほしくない場合、通常のバージョン番号の +後に '_' を使い、、引き続いて最低 2 桁の数字を付けます; 例えば 1.20_01。 +こうするなら、以下の慣用句が推奨されます。 $VERSION = "1.12_01"; $XS_VERSION = $VERSION; # only needed if you have XS code @@ -1537,12 +1491,10 @@ =end 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. -(TBT) +この小技を使うと、MakeMaker は最初の行だけを読むので下線付きで読み、 +一方 perl インタプリタは $VERSION を eval して文字列を数値に変換します。 +これにより、後の操作で $VERSION を数値として扱うものがあっても +$VERSION が数値でないという警告が出なくなります。 =begin original @@ -1552,10 +1504,9 @@ =end 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. -(TBT) +(たとえ 1 文字の文書パッチでも)バージョン番号を増やすことなく何かを +リリースしてはいけません。 +1 文字の文書パッチであっても副マイナー番号を変更するべきです。 =head2 Pre-requisites @@ -1632,9 +1583,8 @@ =end original -Specify version requirements for other Perl modules in the -pre-requisites in your Makefile.PL or Build.PL. -(TBT) +Makefile.PL か Build.PL の pre-requisites に、他の Perl モジュールの +必要バージョンを指定します。 =begin original @@ -1644,10 +1594,9 @@ =end 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. -(TBT) +Makefile.PL や Build.PL と、C<require 5.6.1> のような形の両方で、 +Perl の必要バージョンを指定します。 +詳しくは L<perlfunc/require> の C<use VERSION> の節を参照してください。 =head2 Testing @@ -1662,11 +1611,11 @@ =end 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>. -(TBT) +全てのモジュールは配布する前に ("make disttest" を使って) +テストされるべきですし、テストはモジュールをインストールしようとしている +人々によっても ("make test" を使って) 実行可能であるべきです。 +Module::Build の場合は C<make test> の等価物である C<perl Build test> を +使います。 =begin original @@ -1676,10 +1625,9 @@ =end 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. -(TBT) +これらのテストの重要性はモジュールの安定性に比例します -- 安定していると +表明したり、広く使われることを望むモジュールは、できるだけ厳密なテスト体制に +固執するべきです。 =begin original @@ -1690,11 +1638,9 @@ =end 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. -(TBT) +(開発プロセスや時間に与える影響を最小限にするように) テストを書くのを助ける +モジュールには Test::Simple, Carp::Assert, Test::Inline などがあります。 +さらに洗練されたテストスイートは Test::More と Test::MockObject です。 =head2 Packaging @@ -1712,14 +1658,16 @@ =end 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>. -(TBT) +モジュールは標準的なパッケージングツールの一つを使って +パッケージ化するべきです。 +現在のところ、ExtUtils::MakeMaker および、よりプラットフォーム独立で、 +一貫した方法でモジュールをインストールできる Module::Build という選択肢が +あります。 +ExtUtils::MakeMaker を使うときは、パッケージを作るには "make dist" を +使います。 +MakeMaker 風のスタイルでモジュールをビルドするのを助けるツールがあります。 +これらには ExtUtils::ModuleMaker や h2xs などがあります。 +L<perlnewmod> も参照してください。 =head2 Licensing @@ -1768,12 +1716,13 @@ =end 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. -(TBT) +CPAN によって提供されている、すでにとてもとてもうまくいっている +アプリケーション分野もあります。 +例としてはテンプレートシステムや日付と時間のためのモジュールであり、 +その他にもたくさんあります。 +これらのものの自分専用版を書くというのは通過儀礼ではありますが、 +あなたがそれを公開することを Perl の世界が本当に必要としているかどうかを +慎重に検討してください。 =head2 Trying to do too much @@ -1788,11 +1737,10 @@ =end 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. -(TBT) +あなたのモジュールは開発者のツールキットの一部です。 +ツールキット B<全体> ではありません。 +これはあなたのコードをモジュール化された建築ブロックではなく一枚岩のシステムに +なるまで余分な機能を追加しようとする誘惑です。 =head2 Inappropriate documentation @@ -1807,11 +1755,10 @@ =end 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. -(TBT) +間違った読者に向けて書くという罠に陥らないでください。 +主な読者は、少なくともモジュールの適用分野についてある程度の理解のある +適度に経験を積んだ開発者で、単にモジュールをダウンロードして、できるだけ +早く使い始めたいと思っている人々です。 =begin original @@ -1823,12 +1770,11 @@ =end 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. -(TBT) +チュートリアル、エンドユーザー向け文書、研究論文、FAQ などはモジュールの +主文書としては不適切です。 +どうしてもこれらのものを書きたいなら、C<My::Module::Tutorial> や +C<My::Module::FAQ> のような副文書として含めて、主文書の SEE ALSO 節に +リンクをつけてください。 =head1 SEE ALSO
