diff options
author | Kazuo Horikawa <horikawa@FreeBSD.org> | 2001-12-23 00:24:24 +0000 |
---|---|---|
committer | Kazuo Horikawa <horikawa@FreeBSD.org> | 2001-12-23 00:24:24 +0000 |
commit | 213a645d90589e234ec9dc57a3f654e480b63807 (patch) | |
tree | b68cac779077ef69e1ec085e8622ab02029cc210 /ja_JP.eucJP/man/man9/style.9 | |
parent | f7f125527550d351482346542997c473c797506d (diff) | |
download | doc-213a645d90589e234ec9dc57a3f654e480b63807.tar.gz doc-213a645d90589e234ec9dc57a3f654e480b63807.zip |
Catch up with changes up to Dec 22 (after 4.4-20011213-STABLE)
Notes
Notes:
svn path=/head/; revision=11507
Diffstat (limited to 'ja_JP.eucJP/man/man9/style.9')
-rw-r--r-- | ja_JP.eucJP/man/man9/style.9 | 202 |
1 files changed, 140 insertions, 62 deletions
diff --git a/ja_JP.eucJP/man/man9/style.9 b/ja_JP.eucJP/man/man9/style.9 index 7008fcc31e..f413850a63 100644 --- a/ja_JP.eucJP/man/man9/style.9 +++ b/ja_JP.eucJP/man/man9/style.9 @@ -1,4 +1,4 @@ -.\" Copyright (c) 1995 FreeBSD Inc. +.\" Copyright (c) 1995-2001 FreeBSD Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -25,7 +25,7 @@ .\" %FreeBSD: src/share/man/man9/style.9,v 1.32.2.15 2001/11/26 17:48:15 obrien Exp % .\" $FreeBSD$ .\" -.Dd December 14, 1995 +.Dd December 7, 2001 .Dt STYLE 9 .Os .Sh 名称 @@ -44,7 +44,7 @@ * CSRG の KNF (Kernel Normal Form, カーネル標準書式) に基づいています。 * * @(#)style 1.14 (Berkeley) 4/28/95 - * $\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.15 2001/11/26 17:48:15 obrien Exp $ + * $\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.16 2001/12/17 11:30:19 ru Exp $ */ /* @@ -70,8 +70,12 @@ C/C++ ソースファイルは以降の例に従います。 すべての VCS (バージョン管理システム) リビジョン識別子は、 存在すれば維持します。 これには、ファイルの来歴を示す複数の ID も含みます。 -一般的に、`$' も含めて、ID はそのままとします。 -外部からの VCS ID の前に "From" を付ける理由はありません。 +一般的に、 +.So Li $ Sc +も含めて、ID はそのままとします。 +外部からの VCS ID の前に +.Qq Li "From" +を付ける理由はありません。 ほとんどの非 .Fx の VCS ID は、 @@ -79,15 +83,24 @@ C/C++ ソースファイルは以降の例に従います。 .Bd -literal #include <sys/cdefs.h> __RCSID("@(#)style 1.14 (Berkeley) 4/28/95"); -__FBSDID("$\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.15 2001/11/26 17:48:15 obrien Exp $"); +__FBSDID("$\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.16 2001/12/17 11:30:19 ru Exp $"); .Ed .Pp ヘッダファイルの前に、空行を 1 行付けます。 .Pp -カーネルのインクルードファイル (すなわち、sys/*.h) が初めに来ます。 -通常、<sys/types.h> または <sys/param.h> のどちらかが必要ですが、 +カーネルのインクルードファイル (すなわち、 +.Pa sys/*.h +) が初めに来ます。 +通常、 +.Aq Pa sys/types.h +または +.Aq Pa sys/param.h +のどちらかが必要ですが、 両方は必要ないでしょう。 -<sys/types.h> は <sys/cdefs.h> をインクルードしており、 +.Aq Pa sys/types.h +は +.Aq Pa sys/cdefs.h +をインクルードしており、 依存関係は問題ありません。 .Bd -literal #include <sys/types.h> /* 山括弧による非ローカルインクルード */ @@ -103,14 +116,21 @@ __FBSDID("$\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.15 2001/11/26 17:48:15 #include <protocols/rwhod.h> .Ed .Pp -それから空行を置き、/usr インクルードファイルを続けます。 -/usr インクルードファイルはアルファベット順にソートされているべきです。 +それから空行を置き、 +.Pa /usr +インクルードファイルを続けます。 +.Pa /usr +インクルードファイルはアルファベット順にソートされているべきです。 .Bd -literal #include <stdio.h> .Ed .Pp -グローバルなパス名は /usr/include/paths.h で定義されています。 -プログラムにローカルなパス名はローカルディレクトリの pathnames.h に入れます。 +グローバルなパス名は +.Pa /usr/include/paths.h +で定義されています。 +プログラムにローカルなパス名はローカルディレクトリの +.Qq Pa pathnames.h +に入れます。 .Bd -literal #include <paths.h> .Ed @@ -121,13 +141,15 @@ __FBSDID("$\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.15 2001/11/26 17:48:15 .Ed .Pp アプリケーションインタフェースを実装している場合を除き、 -実装の名前空間で #define したり名前を定義したりしてはいけません。 +実装の名前空間で +.Ic #define +したり名前を定義したりしてはいけません。 .Pp .Dq Li 安全でない マクロ (副作用を持っているもの) の名前と、 明らかな定数のマクロの名前はすべて大文字です。 式のように展開されるマクロは、単一のトークンにするか外側に括弧をつけます。 -.Ql #define +.Ic #define とマクロ名の間にタブ文字を 1 個入れます。 マクロがある関数のインライン展開である場合は、 関数名は全て小文字で、マクロはすべて大文字の同じ名前を持ちます。 @@ -136,16 +158,16 @@ __FBSDID("$\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.15 2001/11/26 17:48:15 .\" これは MALLOC() については言えないし、インライン関数を使う時の .\" 一般的なやりかたではありません。 マクロが 1 行以上必要な場合は、ブレース -.Sq ( \&{ +.Ql ( \&{ と -.Sq \&} ) +.Ql \&} ) を使用します。 バックスラッシュは右揃えします。こうすると読みやすくなります。 マクロが複合文をカプセル化する場合には、それを -.Dq Li do +.Ic do ループで囲みます。 これにより、 -.Dq Li if +.Ic if 文で安全に使用できます。 最後の文の終端のセミコロンは、 マクロではなくマクロの実施時に付けられるべきです。 @@ -174,7 +196,9 @@ enum enumtype { ONE, TWO } et; 重要な構造体は、それが使用されるファイルの先頭で宣言されるか、 複数のソースファイルで使用される場合は別のヘッダファイルで宣言されるべきです。 構造体がヘッダファイルで宣言されている場合には、 -それら構造体の使用は、宣言とは分けられるべきで、かつ "extern" であるべきです。 +それら構造体の使用は、宣言とは分けられるべきで、かつ +.Ic "extern +であるべきです。 .Bd -literal struct foo { struct foo *next; /* 使用中の foo のリスト */ @@ -205,11 +229,12 @@ LIST_HEAD(, foo) foohead; /* グローバルな foo リストの先頭 */ 構造体へのポインタを不透明 (opaque) に使用することが、 アプリケーションにとって不可能となります。 通常の struct タグを使用すると、これが可能となり、かつ有益です。 -規約が typedef を要求する場合には、その名前を構造体タグに一致させます。 -標準 C または -.Tn POSIX +規約が +.Ic typedef +を要求する場合には、その名前を構造体タグに一致させます。 +標準 C または \*[Px] によって明示されたものを除いては、 -.Dq Li \&_t +.Dq Li _t で終る typedef を避けてください。 .Bd -literal /* 構造体名と typedef を一致させます */ @@ -223,20 +248,26 @@ typedef struct bar { 私的な関数 (すなわち、他のどこでも使用されない関数など) の関数プロトタイプは、 最初のソースモジュールの先頭に置かれます。 単一のソースモジュールにローカルな関数は、 -.Ql static +.Ic static で宣言されるべきです。 .Pp カーネルの別の部分から使用される関数は、 関連のあるインクルードファイルの中でプロトタイプされます。 .Pp 複数のモジュールでローカルに使用される関数は、 -.Pa extern.h +.Qq Pa extern.h 等の分離したヘッダファイルの中に置かれます。 .Pp 一般にソースファイルが K&R 旧約聖書コンパイラで コンパイル可能である (べき) 時にのみ、 -インクルードファイル <sys/cdefs.h> の __P マクロを使用します。 -新しいコードでの __P マクロの使用は反対されていますが、 +インクルードファイル +.Aq Pa sys/cdefs.h +の +.Dv __P +マクロを使用します。 +新しいコードでの +.Dv __P +マクロの使用は反対されていますが、 既存のファイルに対する修正はそのファイルの規約と首尾一貫しているべきです。 .Pp ファイルの 50% かそれ以上を巻き込んだ修正の場合は、 @@ -244,7 +275,9 @@ typedef struct bar { .Dq 新しいコード とみなすことができます。 これは既存のコードの慣例を破り、 -現在のスタイルガイドラインを使用するのに十分です。 +現在の +.Nm +ガイドラインを使用するのに十分です。 .Pp カーネルはパラメータの型に関連付けられた名前を持ちます。 例えば、カーネル内でこのように使用します。 @@ -290,12 +323,23 @@ main(int argc, char *argv[]) .Ed .Pp -一貫性のために、オプションの解析には getopt が使用されるべきです。 -getopt 呼び出しと switch 文では、オプションをソートすべきですが、 -switch 文のカスケードの一部の場合は例外です。 -switch 文のカスケード要素は FALLTHROUGH コメントを持つべきです。 +一貫性のために、オプションの解析には +.Xr getopt 3 +が使用されるべきです。 +.Xr getopt 3 +呼び出しと +.Ic switch +文では、オプションをソートすべきですが、 +.Ic switch +文のカスケードの一部の場合は例外です。 +.Ic switch +文のカスケード要素は +.Li FALLTHROUGH +コメントを持つべきです。 数値の引数は精度をチェックされるべきです。 -到達できないコードは NOTREACHED コメントを持つべきです。 +到達できないコードは +.Li NOTREACHED +コメントを持つべきです。 .Bd -literal while ((ch = getopt(argc, argv, "abn:")) != -1) switch (ch) { /* switch をインデント */ @@ -322,10 +366,16 @@ switch 文のカスケード要素は FALLTHROUGH コメントを持つべきです。 argv += optind; .Ed .Pp -予約語 (if, while, for, return, switch) の後にスペースを入れます。 +予約語 +.Pq Ic if , while , for , return , switch +の後にスペースを入れます。 何も伴わないかただ 1 つの文を伴う制御文は、ブレースを使用しません。 1 つの文が 複数行である文の場合には、これは許されます。 -無限ループは while ではなく for で行ないます。 +無限ループは +.Ic while +ではなく +.Ic for +で行ないます。 .Bd -literal for (p = buf; *p != '\e0'; ++p) ; /* 何もなし */ @@ -344,7 +394,8 @@ switch 文のカスケード要素は FALLTHROUGH コメントを持つべきです。 val = realloc(val, newsize); .Ed .Pp -for ループの各部は空のまま残しても構いません。 +.Ic for +ループの各部は空のまま残しても構いません。 異常に複雑なルーチンでない限りは、ブロックの中に宣言を置いてはなりません。 .Bd -literal for (; cnt < 15; cnt++) { @@ -368,7 +419,9 @@ for ループの各部は空のまま残しても構いません。 また、インデントを形成するためには、タブとその後にスペースのみを使用します。 タブが生み出す以上のスペースや、タブの前のスペースは使用しません。 .Pp -ブレースの終了と開始は else と同じ行に置かれます。 +ブレースの終了と開始は +.Ic else +と同じ行に置かれます。 必要でないブレースは省いても構いません。 .Bd -literal if (test) @@ -382,13 +435,13 @@ for ループの各部は空のまま残しても構いません。 .Pp 関数名の後はスペースを空けません。 コンマの後にはスペースを持ちます。 -.Sq \&( +.Ql \&( または -.Sq \&[ +.Ql \&[ の後ろまたは -.Sq \&] +.Ql \&] または -.Sq \&) +.Ql \&) の前にはスペースを空けません。 .Bd -literal error = function(a1, a2); @@ -448,19 +501,30 @@ ANSI C によると、このような宣言は、宣言のネスティングによらず、 ローカルスコープに見えるものの中にファイルの宣言を隠すことは好ましくなく、 良いコンパイラは苦情を言います。 .Pp -キャストと sizeof 演算子の後にはスペースを続けません。 +キャストと +.Ic sizeof +演算子の後にはスペースを続けません。 この規則は .Xr indent 1 が理解しないことに注意してください。 .Pp -NULL は、好まれるヌルポインタ定数です。 +.Dv NULL +は、好まれるヌルポインタ定数です。 コンパイラが型を知っている文脈、例えば代入では、 -(type *)0 または (type *)NULL の代わりに、NULL を使用します。 +.Vt ( "type *" ) Ns 0 +または +.Vt ( "type *" ) Ns Dv NULL +の代わりに、 +.Dv NULL +を使用します。 他の文脈では、特に全ての関数の引数では、 -(type *)NULL を使用します。 +.Vt ( "type *" ) Ns Dv NULL +を使用します。 (関数のプロトタイプがスコープ外かもしれない場合に、 キャストはいろいろな引数にとって必須で、その他の引数にとっても必要です。) -ポインタは NULL と比較します。例えば、 +ポインタは +.Dv NULL +と比較します。例えば、 .Bd -literal !(p = f()) .Ed @@ -470,7 +534,9 @@ NULL は、好まれるヌルポインタ定数です。 (p = f()) == NULL .Ed .Pp -真理値ではない場合、テストには '!' を使用しないでください。 +真理値ではない場合、テストには +.Ic \&! +を使用しないでください。 例えば、下記のように使います。 .Bd -literal if (*p == '\e0') @@ -481,7 +547,8 @@ if (*p == '\e0') if (!*p) .Ed .Pp -void * を返すルーチンでは、 +.Vt "void *" +を返すルーチンでは、 戻り値をどのポインタ型にもキャストしてはなりません。 .Pp .Xr err 3 @@ -533,21 +600,25 @@ usage() /* 関数がローカル変数を持たない場合、空行をいれます */ .Ed .Pp -fputs/puts/putchar 等ではなく、 +.Xr fputs 3 , +.Xr puts 3 , +.Xr putchar 3 +等ではなく、 .Xr printf 3 を使用してください。 これは速くて大抵はきれいで、言うまでもなくつまらないバグを避けます。 .Pp -使用法 (usage) の文はマニュアルページの書式の様であるべきです。 +使用法 (usage) の文はマニュアルページの +.Sx SYNOPSIS +(書式) の様であるべきです。 使用法の文は、次の構造であるべきです: -.Pp .Bl -enum .It オペランドの無いオプションが、最初にアルファベット順に、 1 組の大括弧 -.Sq ( \&[ +.Ql ( \&[ と -.Sq \&] ) +.Ql \&] ) でくくられます。 .It オプションとそのオペランドがこれもアルファベット順に続き、 @@ -564,11 +635,12 @@ fputs/puts/putchar 等ではなく、 .El .Pp 縦棒 -.Pq Sq \&| -は、二者択一のオプションまたは引数を分割し、 +.Pq Ql \&| +は、 +.Dq 二者択一 +のオプションまたは引数を分割し、 同時に使用するオプションと引数は、単一の大括弧でくくります。 -.Pp -.Bd -ragged -offset 4n +.Bd -literal -offset 4n "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" "usage: f [-a | -b] [-c [-dEe] [-n number]]\en" .Ed @@ -583,7 +655,9 @@ fputs/puts/putchar 等ではなく、 つまり、オプションが引数を取るか否かに関わらないということです。 アルファベット順は、前述の大文字小文字の順序を考慮に入れるべきです。 .Pp -新しい中心的なカーネルのコードは、適度にスタイルガイドに従うべきです。 +新しい中心的なカーネルのコードは、適度に +.Nm +ガイドに従うべきです。 サードパーティが保守するモジュールやデバイスドライバのためのガイドラインは より緩やかですが、最低限内部的には彼らの一貫したスタイルであるべきです。 .Pp @@ -591,13 +665,15 @@ fputs/puts/putchar 等ではなく、 正当な理由なしには避けるべきです。 リポジトリの中のおおよそ KNF -.Xr style 9 +.Nm に適合しているコードは、この適合から離れてはなりません。 .Pp 可能な時にはいつでも、 コードはコードチェッカ (例えば、 .Xr lint 1 -または "gcc -Wall") を +または +.Nm gcc Fl Wall +) を 通過し、発生する警告は最小限となるべきです。 .Sh 関連項目 .Xr indent 1 , @@ -608,7 +684,9 @@ KNF .Sh 歴史 このページは .Bx 4.4 Lite2 -リリースの src/admin/style/style ファイルに大きく基づいていて、 +リリースの +.Pa src/admin/style/style +ファイルに大きく基づいていて、 現在の実装と .Fx プロジェクトの要望を反映して、頻繁に更新しています。 |