argra****@users*****
argra****@users*****
2008年 5月 29日 (木) 03:37:28 JST
Index: docs/perl/5.10.0/perlstyle.pod
diff -u /dev/null docs/perl/5.10.0/perlstyle.pod:1.1
--- /dev/null Thu May 29 03:37:28 2008
+++ docs/perl/5.10.0/perlstyle.pod Thu May 29 03:37:28 2008
@@ -0,0 +1,724 @@
+
+=encoding euc-jp
+
+=head1 NAME
+
+=begin original
+
+perlstyle - Perl style guide
+
+=end original
+
+perlstyle - Perl スタイルガイド
+
+=head1 DESCRIPTION
+
+=begin original
+
+Each programmer will, of course, have his or her own preferences in
+regards to formatting, but there are some general guidelines that will
+make your programs easier to read, understand, and maintain.
+
+=end original
+
+プログラマは、もちろん人それぞれ、フォーマットには好みがあるでしょう。
+しかし、いくつかのガイドラインに従うことによって、プログラムの可読性や
+保守性をあげることができます。
+
+=begin original
+
+The most important thing is to run your programs under the B<-w>
+flag at all times. You may turn it off explicitly for particular
+portions of code via the C<no warnings> pragma or the C<$^W> variable
+if you must. You should also always run under C<use strict> or know the
+reason why not. The C<use sigtrap> and even C<use diagnostics> pragmas
+may also prove useful.
+
+=end original
+
+もっとも重要なことは、つねにプログラムを B<-w> フラグをつけて
+走らせることです。
+必要であれば、C<no warnings> プラグマや C<$^W> 変数を使用してコードの
+一部だけで警告を明示的にオフにします。
+また、つねに C<use strict> を使用すべきです。
+もし、C<use strict> を使用しないなら、その理由を十分に理解しておくべきです。
+C<use sigtrap> や C<use diagnostics> プラグマも便利でしょう。
+
+=begin original
+
+Regarding aesthetics of code lay out, about the only thing Larry
+cares strongly about is that the closing curly bracket of
+a multi-line BLOCK should line up with the keyword that started the construct.
+Beyond that, he has other preferences that aren't so strong:
+
+=end original
+
+コードレイアウトの美観に関しては、Larry が強く気にかけているのはたった一つ、
+複数行の BLOCK の閉じ中かっこは、その構造を開始したキーワードと同じ位置に
+なくてはならないということだけです。
+それは別として、そこまで強くはない彼の好みは以下の通りです:
+
+=over 4
+
+=item *
+
+=begin original
+
+4-column indent.
+
+=end original
+
+4 カラムのインデント。
+
+=item *
+
+=begin original
+
+Opening curly on same line as keyword, if possible, otherwise line up.
+
+=end original
+
+可能なら、開始中かっことキーワードを同一行に。
+そうでなければ、開始をそろえる。
+
+=item *
+
+=begin original
+
+Space before the opening curly of a multi-line BLOCK.
+
+=end original
+
+複数行 BLOCK の開始中かっこの前にスペース。
+
+=item *
+
+=begin original
+
+One-line BLOCK may be put on one line, including curlies.
+
+=end original
+
+1 行の BLOCK は中かっこも含め、1 行で。
+
+=item *
+
+=begin original
+
+No space before the semicolon.
+
+=end original
+
+セミコロンの前に空白なし。
+
+=item *
+
+=begin original
+
+Semicolon omitted in "short" one-line BLOCK.
+
+=end original
+
+"短い" 1 行 BLOCK ではセミコロンを省略。
+
+=item *
+
+=begin original
+
+Space around most operators.
+
+=end original
+
+ほとんどの演算子の前後にはスペース。
+
+=item *
+
+=begin original
+
+Space around a "complex" subscript (inside brackets).
+
+=end original
+
+"複雑な"代入(ブラケット内)の前後にはスペース。
+
+=item *
+
+=begin original
+
+Blank lines between chunks that do different things.
+
+=end original
+
+異なることをするチャンクの間には空行。
+
+=item *
+
+=begin original
+
+Uncuddled elses.
+
+=end original
+
+else をくっつけない。
+
+=item *
+
+=begin original
+
+No space between function name and its opening parenthesis.
+
+=end original
+
+関数名と開始カッコの間にはスペースなし。
+
+=item *
+
+=begin original
+
+Space after each comma.
+
+=end original
+
+カンマの後ろにはスペース。
+
+=item *
+
+=begin original
+
+Long lines broken after an operator (except C<and> and C<or>).
+
+=end original
+
+長い行は、演算子の後ろで改行する(C<and> と C<or> を除く)。
+
+=item *
+
+=begin original
+
+Space after last parenthesis matching on current line.
+
+=end original
+
+行の最後のカッコの後ろにスペース。
+
+=item *
+
+=begin original
+
+Line up corresponding items vertically.
+
+=end original
+
+対応する要素の開始位置をそろえる。
+
+=item *
+
+=begin original
+
+Omit redundant punctuation as long as clarity doesn't suffer.
+
+=end original
+
+冗長な表現は、わかりにくくならない限りは省略する。
+
+=back
+
+=begin original
+
+Larry has his reasons for each of these things, but he doesn't claim that
+everyone else's mind works the same as his does.
+
+=end original
+
+Larry にはこれらそれぞれを好む理由がありますが、彼以外の人がこれとまったく
+同じである必要はないといっています。
+
+=begin original
+
+Here are some other more substantive style issues to think about:
+
+=end original
+
+他に、より重要なスタイルの問題を示します:
+
+=over 4
+
+=item *
+
+=begin original
+
+Just because you I<CAN> do something a particular way doesn't mean that
+you I<SHOULD> do it that way. Perl is designed to give you several
+ways to do anything, so consider picking the most readable one. For
+instance
+
+=end original
+
+何かをある方法で I<できる> からといって、そう I<すべき> とは限りません。
+Perl は一つのことを様々な方法でできるように設計されていますから、より
+読みやすいものを選ぶように心がけてください。
+たとえば、
+
+ open(FOO,$foo) || die "Can't open $foo: $!";
+
+=begin original
+
+is better than
+
+=end original
+
+というのは以下のものより良いです:
+
+ die "Can't open $foo: $!" unless open(FOO,$foo);
+
+=begin original
+
+because the second way hides the main point of the statement in a
+modifier. On the other hand
+
+=end original
+
+なぜなら、2 つ目では、この文の主要部が修飾子に隠れてしまっています。
+逆に、
+
+ print "Starting analysis\n" if $verbose;
+
+=begin original
+
+is better than
+
+=end original
+
+というのは以下のものより良いです:
+
+ $verbose && print "Starting analysis\n";
+
+=begin original
+
+because the main point isn't whether the user typed B<-v> or not.
+
+=end original
+
+この文の主要部は、ユーザが B<-v> をタイプしたかどうか
+ではないからです。
+
+=begin original
+
+Similarly, just because an operator lets you assume default arguments
+doesn't mean that you have to make use of the defaults. The defaults
+are there for lazy systems programmers writing one-shot programs. If
+you want your program to be readable, consider supplying the argument.
+
+=end original
+
+同様に、ある演算子がデフォルト引数を想定しているからといって、その
+デフォルトを使わなくてはならないということにはなりません。
+このデフォルト値があるのは、怠惰なシステムプログラマが、一発プログラムを
+書くときのためにあります。
+プログラムを読みやすくするには、引数を省略しないようにしましょう。
+
+=begin original
+
+Along the same lines, just because you I<CAN> omit parentheses in many
+places doesn't mean that you ought to:
+
+=end original
+
+同様に、多くの場所でカッコを省略 I<できます> が、以下のように
+省略しすぎることは控えるべきでしょう:
+
+ return print reverse sort num values %array;
+ return print(reverse(sort num (values(%array))));
+
+=begin original
+
+When in doubt, parenthesize. At the very least it will let some poor
+schmuck bounce on the % key in B<vi>.
+
+=end original
+
+迷ったときは、カッコを書いてください。
+少なくとも、間違えた部分は B<vi> の % キーでハイライトすることができます。
+
+=begin original
+
+Even if you aren't in doubt, consider the mental welfare of the person
+who has to maintain the code after you, and who will probably put
+parentheses in the wrong place.
+
+=end original
+
+迷っていないときも、あとでそのコードをメンテナンスする人の生活を
+考えてください。
+間違った個所にカッコをいれてしまうかもしれません。
+
+=item *
+
+=begin original
+
+Don't go through silly contortions to exit a loop at the top or the
+bottom, when Perl provides the C<last> operator so you can exit in
+the middle. Just "outdent" it a little to make it more visible:
+
+=end original
+
+ループの先頭や末尾で抜け出すのに、ばかげたコードをかかないでください。
+Perl には C<last> 演算子があるので、途中で抜け出すことができます。
+ちょっとだけ読みやすくするには "アウトデント" します:
+
+ LINE:
+ for (;;) {
+ statements;
+ last LINE if $foo;
+ next LINE if /^#/;
+ statements;
+ }
+
+=item *
+
+=begin original
+
+Don't be afraid to use loop labels--they're there to enhance
+readability as well as to allow multilevel loop breaks. See the
+previous example.
+
+=end original
+
+ループのラベルは積極的に使いましょう -- 可読性をあげるのと共に、多段階の
+ループ抜け出しもできるようになります。
+先ほどの例を見てください。
+
+=item *
+
+=begin original
+
+Avoid using C<grep()> (or C<map()>) or `backticks` in a void context, that is,
+when you just throw away their return values. Those functions all
+have return values, so use them. Otherwise use a C<foreach()> loop or
+the C<system()> function instead.
+
+=end original
+
+C<grep()> (や C<map()>)、また `逆クォート` を無効コンテキスト、つまり
+返り値を無視する文で使用しないでください。
+これらの関数はすべて返り値を持っていますから、それを使用してください。
+いらないのであれば、C<foreach()> ループや C<system()> 関数を
+使用してください。
+
+=item *
+
+=begin original
+
+For portability, when using features that may not be implemented on
+every machine, test the construct in an eval to see if it fails. If
+you know what version or patchlevel a particular feature was
+implemented, you can test C<$]> (C<$PERL_VERSION> in C<English>) to see if it
+will be there. The C<Config> module will also let you interrogate values
+determined by the B<Configure> program when Perl was installed.
+
+=end original
+
+ポータビリティのために、すべてのマシンで実装されていないかもしれない機能を
+使用する際は、それを eval で囲って、失敗するかどうかチェックしてください。
+ある機能が、どのバージョンやパッチレベルで実装されているか知っている
+場合には、C<$]> (C<English> モジュールでは、C<$PERL_VERSION>) を
+チェックすることもできます。
+C<Config> モジュールを使えば、Perl インストール時の C<Configure> プログラムに
+よって決定された値を調べることができます。
+
+=item *
+
+=begin original
+
+Choose mnemonic identifiers. If you can't remember what mnemonic means,
+you've got a problem.
+
+=end original
+
+ニーモニックな識別子を選んでください。
+そのニーモニックが何を意味するか思い出せなければ、問題です。
+
+=item *
+
+=begin original
+
+While short identifiers like C<$gotit> are probably ok, use underscores to
+separate words in longer identifiers. It is generally easier to read
+C<$var_names_like_this> than C<$VarNamesLikeThis>, especially for
+non-native speakers of English. It's also a simple rule that works
+consistently with C<VAR_NAMES_LIKE_THIS>.
+
+=end original
+
+C<$gotit> のような短い識別子なら ok ですが、 in longer identifiers 単語を
+区切るにはアンダースコアを使用してください。
+一般的には、とくに英語のネイティブスピーカーでない人にとっては、C<$var_names_like_this> の方が C<$VarNamesLikeThis> より読みやすいです。
+このルールは C<VAR_NAMES_LIKE_THIS> についても同様に当てはまります。
+(TBT)
+
+=begin original
+
+Package names are sometimes an exception to this rule. Perl informally
+reserves lowercase module names for "pragma" modules like C<integer> and
+C<strict>. Other modules should begin with a capital letter and use mixed
+case, but probably without underscores due to limitations in primitive
+file systems' representations of module names as files that must fit into a
+few sparse bytes.
+
+=end original
+
+パッケージ名は、このルールの例外になることがあります。
+Perl は小文字のモジュール名を、C<integer> や C<strict> のような"プラグマ"
+モジュールのために予約しています。
+その他のモジュールは大文字からはじめて、小文字を混ぜて使用すべきですが、
+アンダースコアは使用しません。
+プリミティブなファイルシステムでは、モジュール名をファイルとして
+表現する際に、バイト数の制限があるためです。
+
+=item *
+
+=begin original
+
+You may find it helpful to use letter case to indicate the scope
+or nature of a variable. For example:
+
+=end original
+
+変数のスコープや性質を表現するのに、大文字小文字を使うと便利でしょう。
+たとえば:
+
+=begin original
+
+ $ALL_CAPS_HERE constants only (beware clashes with perl vars!)
+ $Some_Caps_Here package-wide global/static
+ $no_caps_here function scope my() or local() variables
+
+=end original
+
+ $ALL_CAPS_HERE 定数のみ (perl 変数との衝突に注意!)
+ $Some_Caps_Here パッケージワイドなグローバル/スタティック変数
+ $no_caps_here 関数スコープの my(),local()変数
+
+=begin original
+
+Function and method names seem to work best as all lowercase.
+E.g., C<$obj-E<gt>as_string()>.
+
+=end original
+
+関数とメソッドの名前はすべて小文字だとベストです。
+例えば、C<$obj-E<gt>as_string()>。
+
+=begin original
+
+You can use a leading underscore to indicate that a variable or
+function should not be used outside the package that defined it.
+
+=end original
+
+先頭にアンダースコアをつけることによって、変数や関数を定義したパッケージ外で
+使用すべきでないことを命じすることができます。
+
+=item *
+
+=begin original
+
+If you have a really hairy regular expression, use the C</x> modifier and
+put in some whitespace to make it look a little less like line noise.
+Don't use slash as a delimiter when your regexp has slashes or backslashes.
+
+=end original
+
+ほんとにごちゃごちゃな正規表現を使う場合には、C</x> 修飾子を使用して
+スペースをいれ、ごみみたいにならないようにしてください。
+正規表現内にスラッシュやバックスラッシュがあるときには、デリミタに
+スラッシュを使わないように。
+
+=item *
+
+=begin original
+
+Use the new C<and> and C<or> operators to avoid having to parenthesize
+list operators so much, and to reduce the incidence of punctuation
+operators like C<&&> and C<||>. Call your subroutines as if they were
+functions or list operators to avoid excessive ampersands and parentheses.
+
+=end original
+
+新しい C<and> と C<or> 演算子を使用し、リスト演算子のカッコがたくさんに
+なったり、C<&&> や C<||> が大量発生するのを避けてください。
+サブルーチンは、関数やリスト演算子であるかのように扱い、アンパサンドや
+カッコが大量発生するのを避けてください。
+
+=item *
+
+=begin original
+
+Use here documents instead of repeated C<print()> statements.
+
+=end original
+
+C<print()> 文を繰り返さず、ヒアドキュメントを使用してください。
+
+=item *
+
+=begin original
+
+Line up corresponding things vertically, especially if it'd be too long
+to fit on one line anyway.
+
+=end original
+
+対応するものの開始位置はそろえてください、とくに、1行におさまらないものに
+関して。
+
+ $IDX = $ST_MTIME;
+ $IDX = $ST_ATIME if $opt_u;
+ $IDX = $ST_CTIME if $opt_c;
+ $IDX = $ST_SIZE if $opt_s;
+
+ mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
+ chdir($tmpdir) or die "can't chdir $tmpdir: $!";
+ mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!";
+
+=item *
+
+=begin original
+
+Always check the return codes of system calls. Good error messages should
+go to C<STDERR>, include which program caused the problem, what the failed
+system call and arguments were, and (VERY IMPORTANT) should contain the
+standard system error message for what went wrong. Here's a simple but
+sufficient example:
+
+=end original
+
+システムコールの返りコードはつねにチェックしてください。
+良いエラーメッセージは C<STDERR> に書き出され、問題を発生させた
+プログラム名や、失敗したシステムコールと引数、そして(とても重要)標準
+システムエラーメッセージを含むべきです。
+以下はシンプルですが、十分な例です:
+
+ opendir(D, $dir) or die "can't opendir $dir: $!";
+
+=item *
+
+=begin original
+
+Line up your transliterations when it makes sense:
+
+=end original
+
+見やすくなる場合には、tr の開始位置をそろえてください。
+
+ tr [abc]
+ [xyz];
+
+=item *
+
+=begin original
+
+Think about reusability. Why waste brainpower on a one-shot when you
+might want to do something like it again? Consider generalizing your
+code. Consider writing a module or object class. Consider making your
+code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in
+effect. Consider giving away your code. Consider changing your whole
+world view. Consider... oh, never mind.
+
+=end original
+
+再利用性を考慮しましょう。
+同じことをあとでやるかもしれないときに、脳の力を一発のプログラムで
+無駄にする必要はありますか?
+コードの一般化を考慮し、モジュールやオブジェクトクラスを書くことを
+考慮しましょう。
+コードが C<use strict> と C<use warnings> (あるいは B<-w>) が有効でも
+きちんと動くか考慮しましょう。
+コードを捨て去ることも考慮しましょう。
+世界の見方を変えることを考慮しましょう。
+他にも……ああ、もういいや。
+
+=item *
+
+=begin original
+
+Try to document your code and use Pod formatting in a consistent way. Here
+are commonly expected conventions:
+
+=end original
+
+Try to document your code and use Pod formatting in a consistent way. Here
+are commonly expected conventions:
+(TBT)
+
+=over 4
+
+=item *
+
+=begin original
+
+use C<CE<lt>E<gt>> for function, variable and module names (and more
+generally anything that can be considered part of code, like filehandles
+or specific values). Note that function names are considered more readable
+with parentheses after their name, that is C<function()>.
+
+=end original
+
+use C<CE<lt>E<gt>> for function, variable and module names (and more
+generally anything that can be considered part of code, like filehandles
+or specific values). Note that function names are considered more readable
+with parentheses after their name, that is C<function()>.
+(TBT)
+
+=item *
+
+=begin original
+
+use C<BE<lt>E<gt>> for commands names like B<cat> or B<grep>.
+
+=end original
+
+use C<BE<lt>E<gt>> for commands names like B<cat> or B<grep>.
+(TBT)
+
+=item *
+
+=begin original
+
+use C<FE<lt>E<gt>> or C<CE<lt>E<gt>> for file names. C<FE<lt>E<gt>> should
+be the only Pod code for file names, but as most Pod formatters render it
+as italic, Unix and Windows paths with their slashes and backslashes may
+be less readable, and better rendered with C<CE<lt>E<gt>>.
+
+=end original
+
+use C<FE<lt>E<gt>> or C<CE<lt>E<gt>> for file names. C<FE<lt>E<gt>> should
+be the only Pod code for file names, but as most Pod formatters render it
+as italic, Unix and Windows paths with their slashes and backslashes may
+be less readable, and better rendered with C<CE<lt>E<gt>>.
+(TBT)
+
+=back
+
+=item *
+
+=begin original
+
+Be consistent.
+
+=end original
+
+つねに一貫性を。
+
+=item *
+
+=begin original
+
+Be nice.
+
+=end original
+
+つねに素敵に。
+
+=back
+