248 lines
6.3 KiB
Groff
248 lines
6.3 KiB
Groff
.\" Copyright (c) 2000 Josef Karthauser <joe@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" %FreeBSD: src/share/man/man7/style.perl.7,v 1.12.2.3 2001/08/17 13:08:49 ru Exp %
|
|
.\" $FreeBSD: doc/ja_JP.eucJP/man/man7/style.perl.7,v 1.6 2001/07/29 05:15:26 horikawa Exp $
|
|
.\"
|
|
.Dd October 16, 2000
|
|
.Dt STYLE.PERL 7
|
|
.Os
|
|
.Sh 名称
|
|
.Nm style.perl
|
|
.Nd "FreeBSD Perl ソースファイルのスタイルガイド"
|
|
.Sh 解説
|
|
このファイルは
|
|
.Fx
|
|
ソースツリーの perl スクリプトに好ましいスタイルを明記しています。
|
|
.Bd -literal
|
|
#
|
|
# Perl のためのスタイルガイドです。カーネルのスタイルガイドに基づいています。
|
|
#
|
|
|
|
#
|
|
# とても重要な 1 行のコメントはこのようにします。
|
|
#
|
|
|
|
# ほとんどの 1 行コメントはこのようにします。
|
|
|
|
# 複数行にわたるコメントはこのようにします。実際の文章を書きます。実際の
|
|
# 段落に見えるように埋めていきます。
|
|
.Ed
|
|
.Pp
|
|
全てのスクリプトにはスクリプトの先頭に著作権ブロックと、
|
|
そのスクリプトが何をするものなのかを記述したコメントブロックを置くべき
|
|
です。
|
|
.Bd -literal
|
|
#!/usr/bin/perl -w
|
|
|
|
# 著作権
|
|
# ブロック
|
|
|
|
# このスクリプトは標準入力から古いカーネル設定ファイルを読み込み、
|
|
# 標準出力に新しい形式のヒントファイルを出力します。
|
|
.Ed
|
|
.Pp
|
|
全てのスクリプトは
|
|
.Xr strict 3
|
|
モジュールを使用して警告なしに動作しなければいけません。例えば、
|
|
次のようにします:
|
|
.Bd -literal
|
|
#!/usr/bin/perl -w
|
|
|
|
# 著作権、スクリプトの内容記述、その他
|
|
|
|
use strict;
|
|
\&...
|
|
.Ed
|
|
.Pp
|
|
可能な場所ではスクリプトを taint (汚染) モードにして
|
|
動作させてください。このことは
|
|
.Xr perlsec 1
|
|
で文書化されています。
|
|
.Bd -literal
|
|
#!/usr/bin/perl -wT
|
|
.Ed
|
|
.Pp
|
|
メインプログラムは MAIN: とラベルされたブロックに置くべきです。
|
|
これにより大きな perl スクリプトで開始点を識別するのが容易になり、
|
|
またメインプログラムだけで使用される変数に対してスコープを与えます。
|
|
.Bd -literal
|
|
MAIN:{
|
|
print(foo("/usr/bin/man", "7", "style.perl"));
|
|
exit(0);
|
|
}
|
|
.Ed
|
|
.Pp
|
|
全てのサブルーチンは
|
|
.Xr perlsub 1
|
|
で定義されているようなプロトタイプ引数を使用して定義するべきです。
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift;
|
|
my @args = @_;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
全ての変数は使用する前に定義するべきです。これは
|
|
.Ic use strict
|
|
下で利用する場合は強制されます。
|
|
.Pp
|
|
ローカル変数のスコープの定義には
|
|
.Ic local
|
|
.Va $variable
|
|
ではなく
|
|
.Ic my
|
|
.Va $variable
|
|
を用いるべきです。
|
|
.Ic local
|
|
宣言はそれが必要とされる場面にのみ使用し、デフォルトでは使用すべきでは
|
|
ありません。
|
|
たくさんの perl4 スクリプトでは、
|
|
.Ic my
|
|
定義が perl5 以前には存在しなかったという理由で
|
|
.Ic local
|
|
を使用しています。
|
|
.Pp
|
|
多くの場合、グローバル変数はコードの先頭で
|
|
.Xr vars 3
|
|
定義ブロックを使用して定義するべきです:
|
|
.Bd -literal
|
|
use vars qw($globalscalar @globalarray %globalhash);
|
|
.Ed
|
|
.Pp
|
|
場合によってはスクリプトの先頭で
|
|
.Xr vars 3
|
|
宣言ではなく
|
|
.Ic my
|
|
文を用いるのが適していることもあります。
|
|
.Pp
|
|
全ての変数にはコメントをつけるべきです。
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift; # 実行するコマンド
|
|
my @args = @_; # $cmd への引数
|
|
}
|
|
.Ed
|
|
.Pp
|
|
ローカル変数は空行によって関数の引数と分離するべきです:
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift; # 実行するコマンド
|
|
my @args = @_; # command への引数
|
|
|
|
my $pid; # 子の PID
|
|
local *PIPE; # パイプ
|
|
my $output; # コマンドからの出力
|
|
}
|
|
.Ed
|
|
.Pp
|
|
可能な時にはいつでも、
|
|
コードはコードチェッカ
|
|
.Nm perl
|
|
.Fl wc
|
|
.Ar script.pl
|
|
または
|
|
.Nm perl
|
|
.Fl wcT
|
|
.Ar script.pl
|
|
を通過させてください。そのとき、警告が生成されてはいけません。
|
|
.Pp
|
|
インデントは 8 文字のタブです。
|
|
第 2 レベルのインデントは 4 文字のスペースです。
|
|
.Bd -literal
|
|
while (cnt < 20) {
|
|
z = a + really + long + statement + that + needs +
|
|
two lines + gets + indented + four + spaces +
|
|
on + the + second + and + subsequent + lines.
|
|
}
|
|
.Ed
|
|
.Pp
|
|
空白文字を行末に追加してはいけません。
|
|
また、インデントを形成するために、スペースの前にはタブのみを使用して
|
|
ください。
|
|
タブが生み出す以上のスペースおよびタブの前にスペースを使用しては
|
|
いけません。
|
|
.Pp
|
|
ブレースの開始は制御行の最後に置かれます。
|
|
else と elsif は直前の if または elsif ブロックの終了ブレースと
|
|
同じ行に置かれます:
|
|
.Bd -literal
|
|
sub foo($@) {
|
|
my $cmd = shift; # 実行するコマンド
|
|
my @args = @_; # コマンドへの引数
|
|
|
|
my $pid; # 子の PID
|
|
local *PIPE; # パイプ
|
|
my $output; # コマンドからの出力
|
|
|
|
unless (defined($pid = open(PIPE, "-|"))) {
|
|
die("open(): $!\\n");
|
|
} elsif ($pid == 0) {
|
|
exec($cmd, @args);
|
|
die("exec(): $!\\n");
|
|
}
|
|
$output = "";
|
|
while (<PIPE>) {
|
|
$output .= $_;
|
|
}
|
|
waitpid($pid, 0);
|
|
if ($? & 0xff) {
|
|
die("$cmd caught a signal " . ($? & 0x7f) . "\\n");
|
|
} elsif ($?) {
|
|
die("$cmd returned exit code " . ($? >> 8) . "\\n");
|
|
}
|
|
return $output;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
可能な場所では、スクリプトは標準モジュールを使用し、
|
|
コードをその場に書き直してはいけません。
|
|
このことを促進するために、 CPAN モジュールを基本システムに
|
|
取り込むことが適している場合があるかもしれません。
|
|
.Pp
|
|
適切な所では、
|
|
.Ic chop
|
|
ではなく
|
|
.Ic chomp
|
|
を使用してください。
|
|
.Pp
|
|
可読性が増す場合には
|
|
.Ic if Pq Cm \&! No ...\&
|
|
ではなく
|
|
.Ic unless
|
|
を使用してください。
|
|
.Pp
|
|
このガイドに矛盾しない範囲で
|
|
.Xr perlstyle 1
|
|
を読んで Larry Wall の推奨スタイルを採用してください。
|
|
.Sh 関連項目
|
|
.Xr perlsec 1 ,
|
|
.Xr perlstyle 1 ,
|
|
.Xr style 9
|
|
.Sh 歴史
|
|
このマニュアルページは、
|
|
.Fx
|
|
の
|
|
.Xr style 9
|
|
マニュアルページに大きく基づいています。
|