=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 pragma or the C<$^W> variable if you must. You should also always run under C or know the reason why not. The C and even C pragmas may also prove useful. =end original もっとも重要なことは、つねにプログラムを B<-w> フラグをつけて 走らせることです。 必要であれば、C プラグマや C<$^W> 変数を使用してコードの 一部だけで警告を明示的にオフにします。 また、つねに C を使用すべきです; もし、C を 使用しないなら、その理由を十分に理解しておくべきです。 C や C プラグマも便利でしょう。 =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 C). =end original 長い行は、演算子の後ろで改行する(C と C を除く)。 =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 do something a particular way doesn't mean that you I 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 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. =end original 迷ったときは、カッコを書いてください。 少なくとも、間違えた部分は B の % キーでハイライトすることができます。 =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 operator so you can exit in the middle. Just "outdent" it a little to make it more visible: =end original ループの先頭や末尾で抜け出すのに、ばかげたコードをかかないでください; Perl には C 演算子があるので、途中で抜け出すことができます。 ちょっとだけ読みやすくするには "アウトデント" します: 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 (or C) 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 loop or the C function instead. =end original C (や C)、また `逆クォート` を無効コンテキスト、つまり 返り値を無視する文で使用しないでください。 これらの関数はすべて返り値を持っていますから、それを使用してください。 いらないのであれば、C ループや C 関数を 使用してください。 =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) to see if it will be there. The C module will also let you interrogate values determined by the B program when Perl was installed. =end original ポータビリティのために、すべてのマシンで実装されていないかもしれない機能を 使用する際は、それを eval で囲って、失敗するかどうかチェックしてください。 ある機能が、どのバージョンやパッチレベルで実装されているか知っている 場合には、C<$]> (C モジュールでは、C<$PERL_VERSION>) を チェックすることもできます。 C モジュールを使えば、Perl インストール時の C プログラムに よって決定された値を調べることができます。 =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. =end original C<$gotit> のような短い識別子なら ok ですが、より長い識別子の単語を 区切るにはアンダースコアを使用してください。 一般的には、とくに英語のネイティブスピーカーでない人にとっては、 C<$var_names_like_this> の方が C<$VarNamesLikeThis> より読みやすいです。 このルールは C についても同様に当てはまります。 =begin original Package names are sometimes an exception to this rule. Perl informally reserves lowercase module names for "pragma" modules like C and C. 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 や C のような"プラグマ" モジュールのために予約しています。 その他のモジュールは大文字からはじめて、小文字を混ぜて使用すべきですが、 アンダースコアは使用しません; プリミティブなファイルシステムでは、 モジュール名をファイルとして表現する際に、バイト数の制限があるためです。 =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-Eas_string()>. =end original 関数とメソッドの名前はすべて小文字だとベストです。 例えば、C<$obj-Eas_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 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 修飾子を使用して スペースをいれ、ごみみたいにならないようにしてください。 正規表現内にスラッシュやバックスラッシュがあるときには、デリミタに スラッシュを使わないように。 =item * =begin original Use the new C and C 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 と C 演算子を使用し、リスト演算子のカッコがたくさんに なったり、C<&&> や C<||> が大量発生するのを避けてください。 サブルーチンは、関数やリスト演算子であるかのように扱い、アンパサンドや カッコが大量発生するのを避けてください。 =item * =begin original Use here documents instead of repeated C statements. =end original C 文を繰り返さず、ヒアドキュメントを使用してください。 =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, 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 に書き出され、問題を発生させた プログラム名や、失敗したシステムコールと引数、そして(とても重要)標準 システムエラーメッセージを含むべきです。 以下はシンプルですが、十分な例です: 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 and C (or B<-w>) in effect. Consider giving away your code. Consider changing your whole world view. Consider... oh, never mind. =end original 再利用性を考慮しましょう。 同じことをあとでやるかもしれないときに、脳の力を一発のプログラムで 無駄にする必要はありますか? コードの一般化を考慮し、モジュールやオブジェクトクラスを書くことを 考慮しましょう。 コードが C と C (あるいは 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 あなたのコードを文書化して、一貫した方法で Pod フォーマットを使うように 努力してください。 以下は広く想定されている慣習です: =over 4 =item * =begin original use CE> 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. =end original 関数名、変数名、モジュール名(およびより一般的には、ファイルハンドルや 特定の値のような、コードの一部と考えられるもの)には CE> を 使ってください。 関数名は、C のように、名前の後ろにかっこを付けると より読みやすくなると考えられています。 =item * =begin original use CE> for commands names like B or B. =end original B や B のようなコマンド名には CE> を使ってください。 =item * =begin original use CE> or CE> for file names. CE> 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 CE>. =end original ファイル名には CE> か CE> を使ってください。 CE> はファイル名のための唯一の Pod コードであるべきですが、 ほとんどの Pod フォーマッタはこれをイタリック体で表示するため、 Unix と Windows でパスに使われるスラッシュや逆スラッシュが読みにくいです; CE> はよりよく表示されます。 =back =item * =begin original Be consistent. =end original つねに一貫性を。 =item * =begin original Be nice. =end original つねに素敵に。 =back =begin meta Translate: Tatsuhiko Miyagawa (5.8.0) Update: SHIRAKATA Kentaro (5.10.0-) Status: completed =end meta