.\" Copyright (c) 1995 FreeBSD Inc. .\" 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/man9/style.9,v 1.32.2.14 2001/08/17 13:08:54 ru Exp % .\" $FreeBSD: doc/ja_JP.eucJP/man/man9/style.9,v 1.12 2001/08/18 23:48:10 horikawa Exp $ .\" .Dd December 14, 1995 .Dt STYLE 9 .Os .Sh 名称 .Nm style .Nd カーネルソースファイルのスタイルガイド .Sh 解説 このファイルは .Fx ソースツリーのカーネルソースに好ましいスタイルを明記しています。 これはユーザランドのコードスタイルの手引きでもあります。 .\" $ と FreeBSD を続けるとキーワード置換されるので、\& を挿入 .\" 2001/05/23 horikawa@jp.FreeBSD.org .Bd -literal /* * FreeBSD のためのスタイルガイドです。 * CSRG の KNF (Kernel Normal Form, カーネル標準書式) に基づいています。 * * @(#)style 1.14 (Berkeley) 4/28/95 * $\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.14 2001/08/17 13:08:54 ru Exp $ */ /* * とても重要な 1 行のコメントはこのようにします。 */ /* 殆どの 1 行のコメントはこのようにします。 */ /* * 複数行にわたるコメントはこのようにします。実際の文章を書きます。実際の * 段落に見えるように埋めていきます。 */ .Ed .Pp 著作権ヘッダの後には空行を 1 行入れ、ソースファイルには .Va rcsid を付けます。 バージョン管理システムの ID タグは、ファイル中に 1 個のみあるべきです (このファイルでは違いますが)。 C/C++ ソースファイル以外はこの例に従いますが、 C/C++ ソースファイルは以降の例に従います。 外部から入手したファイルの すべての VCS (バージョン管理システム) リビジョン識別子は、維持します。 これには、ファイルの来歴を示す複数の ID も含みます。 一般的に、`$' も含めて、ID はそのままとします。 ほとんどの非 .Fx の VCS ID は、 コメント中ではタブでインデントされているでしょう。 .Bd -literal #ifndef lint #if 0 static char sccsid[] = "@(#)style 1.14 (Berkeley) 4/28/95"; #endif static const char rcsid[] = "$\&FreeBSD: src/share/man/man9/style.9,v 1.32.2.14 2001/08/17 13:08:54 ru Exp $"; #endif /* not lint */ .Ed .Pp この後に空行を 1 行付けます。 .Pp カーネルのインクルードファイル (すなわち、sys/*.h) が初めに来ます。 通常、 または のどちらかが必要ですが、 両方は必要ないでしょう。 は をインクルードしており、 依存関係は問題ありません。 .Bd -literal #include /* 山括弧による非ローカルインクルード */ .Ed .Pp ネットワークプログラムである場合は、 次にネットワークインクルードファイルを置きます。 .Bd -literal #include #include #include #include #include .Ed .Pp それから空行を置き、/usr インクルードファイルを続けます。 /usr インクルードファイルはソートされているべきです。 .Bd -literal #include .Ed .Pp グローバルなパス名は /usr/include/paths.h で定義されています。 プログラムにローカルなパス名はローカルディレクトリの pathnames.h に入れます。 .Bd -literal #include .Ed .Pp それから、空行があって、ユーザインクルードファイルが来ます。 .Bd -literal #include "pathnames.h" /* " " によるローカルインクルード */ .Ed .Pp アプリケーションインタフェースを実装している場合を除き、 実装の名前空間で #define したり名前を定義したりしてはいけません。 .Pp .Dq Li 安全でない マクロ (副作用を持っているもの) の名前と、 明らかな定数のマクロの名前はすべて大文字です。 式のように展開されるマクロは、単一のトークンにするか外側に括弧をつけます。 .Ql #define とマクロ名の間にタブ文字を 1 個入れます。 マクロがある関数のインライン展開である場合は、 関数名は全て小文字で、マクロはすべて大文字の同じ名前を持ちます。 .\" XXX 上記は名前が同じマクロを #undef すれば関数を使える .\" という ANSI のスタイルと衝突します。 .\" これは MALLOC() については言えないし、インライン関数を使う時の .\" 一般的なやりかたではありません。 マクロが 1 行以上必要な場合は、ブレース .Sq ( \&{ と .Sq \&} ) を使用します。 バックスラッシュは右揃えします。こうすると読みやすくなります。 マクロが複合文をカプセル化する場合には、それを .Dq Li do ループで囲みます。 これにより、 .Dq Li if 文で安全に使用できます。 最後の文の終端のセミコロンは、 マクロではなくマクロの実施時に付けられるべきです。 これにより、清書器やエディタで文法解析しやすくなります。 .Bd -literal #define MACRO(x, y) do { \e variable = (x) + (y); \e (y) += 2; \e } while(0) .Ed .Pp 列挙値は全て大文字を使用します。 .Bd -literal enum enumtype { ONE, TWO } et; .Ed .Pp 構造体の中で変数を宣言する時には、 使用順、サイズ順、アルファベット順にソートして宣言します。 最初の区分は通常適用しませんが、例外があります。 各宣言は、それぞれ独立した行にて行います。 最初の語の後にタブ文字を 1 個置きます、すなわち .Ql int^Ix; と .Ql struct^Ifoo *x; です。 .Pp 重要な構造体は、それが使用されるファイルの先頭で宣言されるか、 複数のソースファイルで使用される場合は別のヘッダファイルで宣言されるべきです。 構造体がヘッダファイルで宣言されている場合には、 それら構造体の使用は、宣言とは分けられるべきで、かつ "extern" であるべきです。 .Bd -literal struct foo { struct foo *next; /* 使用中の foo リスト */ struct mumble amumble; /* mumble のコメント */ int bar; }; struct foo *foohead; /* グローバルな foo リストの先頭 */ .Ed .Pp 可能な時には必ず、あなた自身でリストを操作するのではなく、 .Xr queue 3 マクロを使用してください。 従って、前の例をより良く書くと次のようになります。 .Bd -literal #include struct foo { LIST_ENTRY(foo) link; /* foo リスト用のキューマクロの糊 */ struct mumble amumble; /* mumble のコメント */ int bar; }; LIST_HEAD(, foo) foohead; /* グローバルな foo リストの先頭 */ .Ed .Pp 構造体の型に typedef を使用する事は避けてください。 使用してしまうと、 構造体へのポインタを不透明 (opaque) に使用することが、 アプリケーションにとって不可能となります。 通常の struct タグを使用すると、これが可能となり、かつ有益です。 規約が typedef を要求する場合には、その名前を構造体タグに一致させます。 標準 C または .Tn POSIX によって明示されたものを除いては、 .Dq Li \&_t で終る typedef を避けてください。 .Bd -literal /* 構造体名と typedef を一致させます */ typedef struct bar { int level; } BAR; .Ed .Pp 全ての関数はどこかでプロトタイプされます。 .Pp 私的な関数 (すなわち、他のどこでも使用されない関数など) の関数プロトタイプは、 最初のソースモジュールの先頭に置かれます。 単一のソースモジュールにローカルな関数は、 .Ql static で宣言されるべきです。 .Pp カーネルの別の部分から使用される関数は、 関連のあるインクルードファイルの中でプロトタイプされます。 .Pp 複数のモジュールでローカルに使用される関数は、 .Pa extern.h 等の分離したヘッダファイルの中に置かれます。 .Pp 一般にソースファイルが K&R 旧約聖書コンパイラで コンパイル可能である (べき) 時にのみ、 インクルードファイル の __P マクロを使用します。 新しいコードでの __P マクロの使用は反対されていますが、 既存のファイルに対する修正はそのファイルの規約と首尾一貫しているべきです。 .Pp ファイルの 50% かそれ以上を巻き込んだ修正の場合は、 一般にコードは .Dq 新しいコード とみなすことができます。 これは既存のコードの慣例を破り、 現在のスタイルガイドラインを使用するのに十分です。 .Pp カーネルはパラメータの型に関連付けられた名前を持ちます。 例えば、カーネル内でこのように使用します。 .Bd -literal void function(int fd); .Ed .Pp ユーザランドのアプリケーションに対して見えるヘッダファイルの中では、 可視のプロトタイプは、 型を伴った保護された名前を使用するか、 型だけで名前を使用しないかのどちらかが必要です。 保護された名前の使用がより望ましいです。 例えば、このように使用します。 .Bd -literal void function(int); .Ed .Pp または .Bd -literal void function(int _fd); .Ed .Pp プロトタイプは関数名の行揃えを行なうために、タブの後に追加のスペース文字を 置いても構いません。 .Bd -literal static char *function(int _arg, const char *_arg2, struct foo *_arg3, struct bar *_arg4); static void usage(void); /* * 全ての主要なルーチンはそれが何をするのかを簡潔に記述した * コメントを持つべきです。"main" ルーチンの前のコメントは * そのプログラムが何をするのかを記述するべきです。 */ int main(int argc, char *argv[]) { long num; int ch; char *ep; .Ed .Pp 一貫性のために、オプションの解析には getopt が使用されるべきです。 getopt 呼び出しと switch 文では、オプションをソートすべきですが、 switch 文のカスケードの一部の場合は例外です。 switch 文のカスケード要素は FALLTHROUGH コメントを持つべきです。 数値の引数は精度をチェックされるべきです。 到達できないコードは NOTREACHED コメントを持つべきです。 .Bd -literal while ((ch = getopt(argc, argv, "abn:")) != -1) switch (ch) { /* switch をインデント */ case 'a': /* case はインデントしない */ aflag = 1; /* FALLTHROUGH */ case 'b': bflag = 1; break; case 'n': num = strtol(optarg, &ep, 10); if (num <= 0 || *ep != '\e0') { warnx("illegal number, -n argument -- %s", optarg); usage(); } break; case '?': default: usage(); /* NOTREACHED */ } argc -= optind; argv += optind; .Ed .Pp 予約語 (if, while, for, return, switch) の後にスペースを入れます。 何も伴わないかただ 1 つの文を伴う制御文は、ブレースを使用しません。 1 つの文が 複数行である文の場合には、これは許されます。 無限ループは while ではなく for で行ないます。 .Bd -literal for (p = buf; *p != '\e0'; ++p) ; /* 何もなし */ for (;;) stmt; for (;;) { z = a + really + long + statement + that + needs + two lines + gets + indented + four + spaces + on + the + second + and + subsequent + lines; } for (;;) { if (cond) stmt; } if (val != NULL) val = realloc(val, newsize); .Ed .Pp for ループの各部は空のまま残しても構いません。 異常に複雑なルーチンでない限りは、ブロックの中に宣言を置いてはなりません。 .Bd -literal for (; cnt < 15; cnt++) { stmt1; stmt2; } .Ed .Pp インデントは 8 文字のタブです。 第 2 レベルのインデントは 4 文字のスペースです。 長い分を折り返す必要がある場合、オペレータを行末に置きます。 .Bd -literal while (cnt < 20 && this_variable_name_is_too_long_for_its_own_good && ep != NULL) z = a + really + long + statement + that + needs + two lines + gets + indented + four + spaces + on + the + second + and + subsequent + lines; .Ed .Pp 空白文字を行末に追加してはいけません。 また、インデントを形成するためには、タブとその後にスペースのみを使用します。 タブが生み出す以上のスペースや、タブの前のスペースは使用しません。 .Pp ブレースの終了と開始は else と同じ行に置かれます。 必要でないブレースは省いても構いません。 .Bd -literal if (test) stmt; else if (bar) { stmt; stmt; } else stmt; .Ed .Pp 関数名の後はスペースを空けません。 コンマの後にはスペースを持ちます。 .Sq \&( または .Sq \&[ の後ろまたは .Sq \&] または .Sq \&) の前にはスペースを空けません。 .Bd -literal error = function(a1, a2); if (error != 0) exit(error); .Ed .Pp 単項演算子はスペースを要求しませんが、二項演算子は要求します。 優先順位が要求する場合または文が括弧なしでは混乱する場合以外は、 括弧は使用しません。 他人はあなたよりも混乱しやすいかもしれないということを覚えておいてください。 あなたは以下を理解できますか? .Bd -literal a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; k = !(l & FLAGS); .Ed .Pp 成功時には 0 で、または .Xr sysexits 3 にあらかじめ定義してある値で exit するべきです。 .Bd -literal exit(EX_OK); /* * "Exit 0 on success." (成功時は 0 で終了) * の様に明白なコメントは避けてください */ } .Ed .Pp 関数の型は、関数自身に先行する行にあるべきです。 .Bd -literal static char * function(int a1, int a2, float fl, int a4) { .Ed .Pp 関数の中で変数を宣言する時には、サイズ順に、次にアルファベット順に ソートして宣言します。 1 行に複数の宣言は可能です。 行が溢れる場合は、型の予約語を再度使用します。 .Pp 宣言時に変数を初期化することによってコードを 不明瞭にしない様に注意してください。 この機能は良く考えて使用してください。 初期化に関数呼び出しを使用しないでください。 .Bd -literal struct foo one, *two; double three; int *four, five; char *six, seven, eight, nine, ten, eleven, twelve; four = myfunction(); .Ed .Pp 他の関数の内部で関数を宣言しないでください。 ANSI C によると、このような宣言は、宣言のネスティングによらず、 ファイルスコープになります。 ローカルスコープに見えるものの中にファイルの宣言を隠すことは好ましくなく、 良いコンパイラは苦情を言います。 .Pp キャストと sizeof 演算子の後にはスペースを続けません。 この規則は .Xr indent 1 が理解しないことに注意してください。 .Pp NULL は、好まれるヌルポインタ定数です。 コンパイラが型を知っている文脈、例えば代入では、 (type *)0 または (type *)NULL の代わりに、NULL を使用します。 他の文脈では、特に全ての関数の引数では、 (type *)NULL を使用します。 (関数のプロトタイプがスコープ外かもしれない場合に、 キャストはいろいろな引数にとって必須で、その他の引数にとっても必要です。) ポインタは NULL と比較します。例えば、 .Bd -literal !(p = f()) .Ed .Pp ではなく、このように使います。 .Bd -literal (p = f()) == NULL .Ed .Pp 真理値ではない場合、テストには '!' を使用しないでください。 例えば、下記のように使います。 .Bd -literal if (*p == '\e0') .Ed .Pp 下記のようには使いません。 .Bd -literal if (!*p) .Ed .Pp void * を返すルーチンでは、 戻り値をどのポインタ型にもキャストしてはなりません。 .Pp .Xr err 3 または .Xr warn 3 を使用し、勝手に作らないでください。 .Bd -literal if ((four = malloc(sizeof(struct foo))) == NULL) err(1, (char *)NULL); if ((six = (int *)overflow()) == NULL) errx(1, "number overflowed"); return (eight); } .Ed .Pp 古いスタイルの関数宣言はこのようになっています。 .Bd -literal static char * function(a1, a2, fl, a4) int a1, a2; /* int 型も宣言します、デフォルトにしないこと */ float fl; /* double と float の違いに気を付けてください */ int a4; /* 出てきた順に宣言します */ { .Ed .Pp あなたが明確に K&R との互換性を必要とする場合以外は、 ANSI の関数宣言を使用してください。 長いパラメータリストの折り返しには、 4 個の空白による通常のインデントを付けます。 .Pp 可変個数の引数はこのようにします。 .Bd -literal #include void vaf(const char *fmt, ...) { va_list ap; va_start(ap, fmt); STUFF; va_end(ap); /* void 型の関数に return は不要です */ } static void usage() { /* 関数がローカル変数を持たない場合、空行をいれます */ .Ed .Pp fputs/puts/putchar 等ではなく、 .Xr printf 3 を使用してください。 これは速くて大抵はきれいで、言うまでもなくつまらないバグを避けます。 .Pp 使用法 (usage) の文はマニュアルページの書式の様であるべきです。 使用法の文は、次の構造であるべきです: .Pp .Bl -enum .It オペランドの無いオプションが、最初にアルファベット順に、 1 組の大括弧 .Sq ( \&[ と .Sq \&] ) でくくられます。 .It オプションとそのオペランドがこれもアルファベット順に続き、 それぞれのオプションとその引数を 1 組の大括弧でくくります。 .It 必須の引数 (もしあれば) が続き、 コマンドラインで指定されるべき順で一覧されます。 .It 最後に、 すべての任意の引数が指定されるべき順で、 すべて大括弧の中に一覧されます。 .El .Pp 縦棒 .Pq Sq \&| は、二者択一のオプションまたは引数を分割し、 同時に使用するオプションと引数は、単一の大括弧でくくります。 .Pp .Bd -ragged -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 .Bd -literal (void)fprintf(stderr, "usage: f [-ab]\en"); exit(EX_USAGE); } .Ed .Pp 新しい中心的なカーネルのコードは、適度にスタイルガイドに従うべきです。 サードパーティが保守するモジュールやデバイスドライバのためのガイドラインは より緩やかですが、最低限内部的には彼らの一貫したスタイルであるべきです。 .Pp ソースリポジトリの文体の変更 (空白文字の変更を含む) は困難で、 正当な理由なしには避けるべきです。 リポジトリの中のおおよそ KNF .Xr style 9 に適合しているコードは、この適合から離れてはなりません。 .Pp 可能な時にはいつでも、 コードはコードチェッカ (例えば、 .Xr lint 1 または "gcc -Wall") を 通過し、発生する警告は最小限となるべきです。 .Sh 関連項目 .Xr indent 1 , .Xr lint 1 , .Xr err 3 , .Xr sysexits 3 , .Xr warn 3 .Sh 歴史 このページは .Bx 4.4 Lite2 リリースの src/admin/style/style ファイルに大きく基づいていて、 現在の実装と .Fx プロジェクトの要望を反映して、更新してあります。