Linux Kernel 2.6 Documentation:
/usr/src/linux/Documentation/CodingStyle
CodingStyle
Linux カーネル コーディング規約
[プレインテキスト版]
- 原著作者: Linus Torvalds <torvalds at osdl dot org>
- 翻訳者: Ken Iwamoto <iwamoto dot kn at ncos dot nec dot co dot jp> Toshikazu Nakayama <nakayama dot ts at ncos dot nec dot co dot jp> Nobuo Yoshida <yoshida dot nb at ncos dot nec dot co dot jp>
- バージョン: 2.6.24
- 翻訳日時: 2008/03/26
==================================
これは、
linux-2.6.24/Documentation/CodingStyle の和訳
です。
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
更新日 ： 2008/3/26
翻訳者 ： Ken Iwamoto <iwamoto dot kn at ncos dot nec dot co dot jp>
Toshikazu Nakayama <nakayama dot ts at ncos dot nec dot co dot jp>
Nobuo Yoshida <yoshida dot nb at ncos dot nec dot co dot jp>
校正者 ： Masanori Kobayasi さん <zap03216 at nifty dot ne dot jp>
Seiji Kaneko さん <skaneko at a2 dot mbn dot or dot jp>
池田 さん <m-ikeda at ds dot jp dot nec dot com>
来山 さん <i-kitayama at ap dot jp dot nec dot com>
Hiro YAMAZAKI さん <hiro dot yamazaki at physics dot ox dot ac dot uk>
==================================
Linux kernel coding style
Linux カーネル コーディング規約
This is a short document describing the preferred coding style for the
linux kernel. Coding style is very personal, and I won't _force_ my
views on anybody, but this is what goes for anything that I have to be
able to maintain, and I'd prefer it for most other things too. Please
at least consider the points made here.
この文書では、Linux カーネルのソースコードの好ましい書き方を簡単に説明し
ています。コーディングの仕方は非常に好みが分かれるものだから、私の考えを
強制するつもりはありません。でも、これから説明することは私が管理しなくて
はならないこと全てに当てはまる方針ですし、私は自分が管理しないものでも、
この方針で書かれていれば良いのにとさえ思っています。せめて、この文書に
書かれたことだけでも守ってください。
First off, I'd suggest printing out a copy of the GNU coding standards,
and NOT read it. Burn them, it's a great symbolic gesture.
まず最初に、「GNU コーディング規約」(GNU coding standards)を入手して印刷
してみてください。でも、読むために印刷するのではありません。印刷した物を
燃やすのです。この儀式は晴れがましい意思表示なのです。
Anyway, here goes:
とにかく、本題に入りましょう -
Chapter 1: Indentation
第１章 - インデント
Tabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!)
characters deep, and that is akin to trying to define the value of PI to
be 3.
タブは８文字です。なので、インデントも８文字です。インデントを４文字にし
たり、更には２文字にしようというような異教徒の運動までありますけれど、こ
れはπ＝３と決めてしまおうという主張と同じようなものです。
Rationale: The whole idea behind indentation is to clearly define where
a block of control starts and ends. Especially when you've been looking
at your screen for 20 straight hours, you'll find it a lot easier to see
how the indentation works if you have large indentations.
論拠 - そもそもインデントとは、ブロックの始まりと終わりをはっきりさせるた
めのものです。大きなインデントの恩恵は、２０時間連続してモニタを眺めてい
るときなどに特に実感できます。
Now, some people will claim that having 8-character indentations makes
the code move too far to the right, and makes it hard to read on a
80-character terminal screen. The answer to that is that if you need
more than 3 levels of indentation, you're screwed anyway, and should fix
your program.
さて、人によっては「８文字単位にインデントをすると、プログラムが右に行き
過ぎて、８０文字の画面では読みにくくなってしまう」と主張するでしょう。こ
ういう人達には、「３段階より多くのインデントをするような場合は、プログラ
ムそのものが良くないのだから、そこを修正しなさい」と言いましょう。
In short, 8-char indents make things easier to read, and have the added
benefit of warning you when you're nesting your functions too deep.
Heed that warning.
要するに、８文字単位のインデントをすればプログラムが読みやすくなり、その
上、ネストが深過ぎる関数を書いてしまった場合の警告にもなります。警告を素
直に聞き入れてください。
The preferred way to ease multiple indentation levels in a switch statement is
to align the "switch" and its subordinate "case" labels in the same column
instead of "double-indenting" the "case" labels. E.g.:
switch 文でインデントのレベルを浅くするのに推奨する方法は、「case」ラベル
を「ダブルインデント」にする代わりに、「switch」とそれに含まれる「case」ラ
ベルを同じ列にそろえることです。例 -
switch (suffix) {
case 'G':
case 'g':
mem <<= 30;
break;
case 'M':
case 'm':
mem <<= 20;
break;
case 'K':
case 'k':
mem <<= 10;
/* fall through */
default:
break;
}
Don't put multiple statements on a single line unless you have
something to hide:
何か隠したいことがない限り、１行に複数の文を書かないでください -
if (condition) do_this;
do_something_everytime;
if ( 条件文 ) ここですること;
どんな時でもすること;
Don't put multiple assignments on a single line either. Kernel coding style
is super simple. Avoid tricky expressions.
１行に複数の処理を書かないでください。カーネルのコーディングスタイルは、と
ても単純であるべきです。凝った表現は避けてください。
Outside of comments, documentation and except in Kconfig, spaces are never
used for indentation, and the above example is deliberately broken.
コメントやドキュメーテンション以外では、決して空白でインデントしてはいけ
ません（ただし Kconfig ファイルを除く）。ちなみに上記の例はあえてやって
います。
Get a decent editor and don't leave whitespace at the end of lines.
まともなエディタを使ってください、そして行の最後に空白文字を置かないでく
ださい。
Chapter 2: Breaking long lines and strings
第２章 - 長い行と長い文字列を分離して短くすること
Coding style is all about readability and maintainability using commonly
available tools.
コーディング規約の目的は、一般的なツールを使用した場合に、読みやすさと保
守のしやすさを確保することにあります。
The limit on the length of lines is 80 columns and this is a strongly
preferred limit.
行の長さは８０カラムが限界で、これは強く推奨される制限です。
Statements longer than 80 columns will be broken into sensible chunks.
Descendants are always substantially shorter than the parent and are placed
substantially to the right. The same applies to function headers with a long
argument list. Long strings are as well broken into shorter strings. The
only exception to this is where exceeding 80 columns significantly increases
readability and does not hide information.
８０カラムより長い文は、分かりやすいように分割しましょう。分割の２行目以
降は１行目より常にかなり短くし、かなり右に置きます。同じことが、長い引数
リストを持つ関数宣言にも適用できます。同様に、長い文字列もより短い文字列
に分割できます。これに対する唯一の例外は、８０カラムを越えることで、読み
やすさが格段に向上する上に、情報が隠されない場合です。
void fun(int a, int b, int c)
{
if (condition)
printk(KERN_WARNING "Warning this is a long printk with "
"3 parameters a: %u b: %u "
"c: %u \n", a, b, c);
else
next_statement;
}
void fun(int a, int b, int c)
{
if ( 条件文 )
printk(KERN_WARNING "Warning this is a long printk with "
"3 parameters a: %u b: %u "
"c: %u \n", a, b, c);
else
次の文 ;
}
Chapter 3: Placing Braces and Spaces
第３章 - 括弧の位置と空白
The other issue that always comes up in C styling is the placement of
braces. Unlike the indent size, there are few technical reasons to
choose one placement strategy over the other, but the preferred way, as
shown to us by the prophets Kernighan and Ritchie, is to put the opening
brace last on the line, and put the closing brace first, thusly:
Ｃ言語のコーディング規約で、もう一つ、よく話題になるのが括弧の位置です。
インデントの場合とは違い、どこに括弧を置くのが優れているかというような
技術的な根拠はほとんどありません。それでも好ましい括弧の位置というのは
あって、Kernighan と Ritchie 両氏によるＣ言語の聖典（通称 K&R と呼ばれ
る「プログラミング言語Ｃ」）に示されているのです。ブロックの開始行の行
末に開始括弧を置いて、ブロックの最終行の始まりに終了括弧を置くというも
ので、次のようになります -
if (x is true) {
we do y
}
if ( xが真 ) {
yを実行;
}
This applies to all non-function statement blocks (if, switch, for,
while, do). E.g.:
これは、関数以外のブロック全て（if、switch、for、while、do）にあてはまり
ます。例 -
switch (action) {
case KOBJ_ADD:
return "add";
case KOBJ_REMOVE:
return "remove";
case KOBJ_CHANGE:
return "change";
default:
return NULL;
}
However, there is one special case, namely functions: they have the
opening brace at the beginning of the next line, thus:
ただし、関数定義の括弧だけは例外で、開始括弧は次の行の始まりに置きます -
int function(int x)
{
body of function
}
int 関数名(int x)
{
関数の中身
}
Heretic people all over the world have claimed that this inconsistency
is ... well ... inconsistent, but all right-thinking people know that
(a) K&R are _right_ and (b) K&R are right. Besides, functions are
special anyway (you can't nest them in C).
ところが世界中の異教徒たちは、この一貫性の無さが、...そうですね...一貫
性が無いと文句を言っています。しかし、正しい思想を持った人々は (a)
K&R は正しく、しかも(b) K&R が正しいのだとわかっています。それに、とに
かく関数定義というのは特別なものなのです（Ｃ言語の中で関数定義のネスト
はできません）。
Note that the closing brace is empty on a line of its own, _except_ in
the cases where it is followed by a continuation of the same statement,
ie a "while" in a do-statement or an "else" in an if-statement, like
this:
ここで一つ注意しておきます。終了括弧は普通、終了括弧だけの行になります
が、終了括弧で文が終わらない場合にはその行が続くことになります。すなわ
ち do 文では "while" が、 if 文では "else" が来ることがあります -
do {
body of do-loop
} while (condition);
and
if (x == y) {
..
} else if (x > y) {
...
} else {
....
}
do {
doループの中身
} while ( 条件文 );
や、
if (x == y) {
..
} else if (x > y) {
...
} else {
....
}
Rationale: K&R.
論拠 - 聖典「K&R」
Also, note that this brace-placement also minimizes the number of empty
(or almost empty) lines, without any loss of readability. Thus, as the
supply of new-lines on your screen is not a renewable resource (think
25-line terminal screens here), you have more empty lines to put
comments on.
それに、ここで説明したように括弧を置けば、読みやすさを犠牲にしないで、
空行（というか、ほとんど空行）を最小限にとどめることができるでしょう。画
面に表示できる行は限られていますが（ここでは２５行の端末画面を念頭に置い
て話をしています）、このようにして空行を減らした分、コメントを入れること
ができます。
Do not unnecessarily use braces where a single statement will do.
１つの文しか実行しないところに、必要のない括弧を使わないでください。
if (condition)
action();
if ( 条件文 )
action();
This does not apply if one branch of a conditional statement is a single
statement. Use braces in both branches.
これは、条件文の片方の分岐が１つの文である場合、あてはまりません。両方の分
岐に括弧を使用してください。
if (condition) {
do_this();
do_that();
} else {
otherwise();
}
if ( 条件文 ) {
do_this();
do_that();
} else {
otherwise();
}
3.1: Spaces
３．１ - 空白
Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
somewhat like functions (and are usually used with parentheses in Linux,
although they are not required in the language, as in: "sizeof info" after
"struct fileinfo info;" is declared).
Linux カーネルスタイルにおける空白の使用方法は、（主に）関数かキーワードか
によって変わります。（大部分の）キーワードの後には、空白を使ってください。
注意すべき例外は、関数のように見える sizeof、typeof、alignof、__attribute__
です。（これらは、"struct fileinfo info;" の定義後に "sizeof info" が使える
ように、言語仕様上、必ずしも括弧は必要ではないけれども、Linux では通常、括
弧を使います）。
So use a space after these keywords:
だから以下のキーワードの後には、空白を使ってください -
if, switch, case, for, do, while
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
しかし、sizeof、typeof、alignof、__attribute__ の後には空白を使わないでくだ
さい。例 -
s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is
*bad*:
括弧内の式の前後に、空白を使わないでください。以下の例は悪い例です -
s = sizeof( struct file );
When declaring pointer data or a function that returns a pointer type, the
preferred use of '*' is adjacent to the data name or function name and not
adjacent to the type name. Examples:
ポインタデータ、またはポインタ型を返す関数を定義するとき、「*」の良い使い
方はデータ名または関数名にはつけて、型名につけません。例 -
char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);
Use one space around (on each side of) most binary and ternary operators,
such as any of these:
以下のように、たいていの二項演算子や三項演算子の演算子の回りに（前後に）、
空白を１文字使ってください -
= + - < > * / % | & ^ <= >= == != ? :
but no space after unary operators:
しかし単項演算子の後には、空白を使わないでください -
& * + - ~ ! sizeof typeof alignof __attribute__ defined
no space before the postfix increment & decrement unary operators:
後置インクリメント単項演算子や後置デクリメント単項演算子の前には、空白を使
わないでください -
++ --
no space after the prefix increment & decrement unary operators:
前置インクリメント単項演算子や前置デクリメント単項演算子の後に空白を使わな
いでください -
++ --
and no space around the '.' and "->" structure member operators.
そして、構造体演算子「.」と「->」の前後に、空白を使わないでください。
Do not leave trailing whitespace at the ends of lines. Some editors with
"smart" indentation will insert whitespace at the beginning of new lines as
appropriate, so you can start typing the next line of code right away.
However, some such editors do not remove the whitespace if you end up not
putting a line of code there, such as if you leave a blank line. As a result,
you end up with lines containing trailing whitespace.
行末に無駄な空白を残さないでください。気の利いたインデント機能を持つエディ
タは、新しい行の先頭に適切な空白を挿入してくれるので、次の行から、すぐにコ
ードを書き始めることができます。しかしながら、そのようなエディタの中には、
あなたが空白行を残そうとして、コードを追加しなかった時、空白を削除してくれ
ないものがあります。その結果、行末に無駄な空白が残ります。
Git will warn you about patches that introduce trailing whitespace, and can
optionally strip the trailing whitespace for you; however, if applying a series
of patches, this may make later patches in the series fail by changing their
context lines.
git は行末に無駄な空白のあるパッチに対して、警告してくれるでしょう、そして
無駄な空白を任意に取り除くことができます - しかしながら、複数のパッチを適用
する場合、git がある行末の無駄な空白を削除することで、同じ行を変更する、あと
から適用するパッチが失敗するかもれしれません。
Chapter 4: Naming
第４章 - 名前の選択
C is a Spartan language, and so should your naming be. Unlike Modula-2
and Pascal programmers, C programmers do not use cute names like
ThisVariableIsATemporaryCounter. A C programmer would call that
variable "tmp", which is much easier to write, and not the least more
difficult to understand.
Ｃ言語はスパルタ言語なのですから、それにふさわしく変数や関数を命名しまし
ょう。Modula-2 や Pascal のプログラマとは違って、Ｃ言語プログラマは 「こ
の変数は一時的に使われるカウンターである(ThisVariableIsATemporaryCounter)」
などというような気のきいた名前は使いません。Ｃ言語プログラマは、"tmp" な
どの十分に書きやすく、それでいて少なくとも分かりにくくはならない変数名を
選ぶものです。
HOWEVER, while mixed-case names are frowned upon, descriptive names for
global variables are a must. To call a global function "foo" is a
shooting offense.
大文字小文字を混ぜたような名前は嫌がられますが、グローバル変数には、意味
のわかる名前が必要です。グローバル関数に "foo" などという無意味な名前を
付けることは不快感を与えてしまいます。
GLOBAL variables (to be used only if you _really_ need them) need to
have descriptive names, as do global functions. If you have a function
that counts the number of active users, you should call that
"count_active_users()" or similar, you should _not_ call it "cntusr()".
グローバル変数（本当に必要な時にだけ使うこと）には意味がよく分かる名前
を付けてください。グローバル関数も同じで、アクティブなユーザ数を数える
グローバル関数には "count_active_users()" やそれに類似した名前を使うべ
きであり、"cntusr()" を使うべきではありません。
Encoding the type of a function into the name (so-called Hungarian
notation) is brain damaged - the compiler knows the types anyway and can
check those, and it only confuses the programmer. No wonder MicroSoft
makes buggy programs.
関数の型を関数名に含める方式（いわゆるハンガリー記法）は、明らかに間違っ
ています。そんなことをしなくても、とにかくコンパイラは型を知っていますし、
型のチェックもできます。結局はプログラマ自身を混乱させるだけです。
Microsoft がバグの多いプログラムを作っているのも不思議ではありません。
LOCAL variable names should be short, and to the point. If you have
some random integer loop counter, it should probably be called "i".
Calling it "loop_counter" is non-productive, if there is no chance of it
being mis-understood. Similarly, "tmp" can be just about any type of
variable that is used to hold a temporary value.
ローカル変数の名前は短くて、変数の特徴を表したものにします。ループの実
行回数を数える適当な整数カウンタを選ぶならば、おろらく "i" と名付けるべ
きです。誤解されることもないのに、loop_counter と呼ぶことは実りがありま
せん。同様に、一時的に値を保持するテンポラリ変数は型に係わらず、単に
tmp としましょう。
If you are afraid to mix up your local variable names, you have another
problem, which is called the function-growth-hormone-imbalance syndrome.
See chapter 6 (Functions).
もしローカル変数の名前付けに迷っているようなら、別な問題を抱えているもの
です。「関数成長ホルモン不均衡症候群」と呼ばれています。詳しくは第６章（
関数）を見てください。
Chapter 5: Typedefs
第５章 - Typedef
Please don't use things like "vps_t".
"vps_t" のような定義は使わないでください。
It's a _mistake_ to use typedef for structures and pointers. When you see a
vps_t a;
in the source, what does it mean?
構造体やポインタに typedef を使うことが間違っています。ソース上で、
「vps_t a;」という文を見たとき、どんな意味があると考えますか？
In contrast, if it says
struct virtual_container *a;
you can actually tell what "a" is.
対照的に、「struct virtual_container *a;」なら、"a" が何であるか、実際
に言い当てることができます。
Lots of people think that typedefs "help readability". Not so. They are
useful only for:
typedef の定義は「読みやすさの手助け」になると、多くの人々は考えています。
しかしそうではありません。typedef は次の場合にだけ役に立ちます。
(a) totally opaque objects (where the typedef is actively used to _hide_
what the object is).
(a) 内部を知る必要ないオブジェクト（そのオブジェクトが何であるかを隠蔽す
るため、積極的に typedef を使用する場合）
Example: "pte_t" etc. opaque objects that you can only access using
the proper accessor functions.
例えば - "pte_t" などの、適切な操作関数を使ってのみアクセスする
ことができる、内部を知る必要のないオブジェクト。
NOTE! Opaqueness and "accessor functions" are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely _zero_ portably accessible information there.
ここで注意です！内部を知る必要ないデータ構造と「操作関数」は、それ
自体良くありません。pte_t などがそうなっている理由は、移植性のある
アクセス可能な情報が完全に「なにもない」からです。
(b) Clear integer types, where the abstraction _helps_ avoid confusion
whether it is "int" or "long".
(b) int 型か long 型か考慮する必要なく、抽象化によって整数型だということ
だけをはっきりさせたい場合。
u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.
このカテゴリより、カテゴリ(d) に関連しますが、u8/u16/u32 は何の問題も
ない typedef 定義です。
NOTE! Again - there needs to be a _reason_ for this. If something is
"unsigned long", then there's no reason to do
typedef unsigned long myflags_t;
再度注意です！これには理由が必要です。unsined long 型として扱える変
数の型を以下のように再定義する理由は何もありません。
typedef unsigned long myflags_t;
but if there is a clear reason for why it under certain circumstances
might be an "unsigned int" and under other configurations might be
"unsigned long", then by all means go ahead and use a typedef.
ある環境では unsigned int 型であり、他の環境では unsigned long 型で
あるようなはっきりとした理由がある場合には、ぜひとも typedef を使っ
てください。
(c) when you use sparse to literally create a _new_ type for
type-checking.
(c) sparse ツールを使った型チェック用に、文字通り「新しい型」を定義する
場合。
(d) New types which are identical to standard C99 types, in certain
exceptional circumstances.
(d) 特例として、C99 で導入された新しい標準型と同じ型を定義する場合。
Although it would only take a short amount of time for the eyes and
brain to become accustomed to the standard types like 'uint32_t',
some people object to their use anyway.
目と脳は「uint32_t」のような標準型にすぐ慣れますが、それでもこのよう
な型を使うことに反対する人たちがいます。
Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
signed equivalents which are identical to standard types are
permitted -- although they are not mandatory in new code of your
own.
そのため、C99の標準型と全く同じですが、Linux 特有の u8/u16/u32/u64
という型と、それらの符号付きの型が定義されています。 - といっても、
あなたが新しいコードを書くときに、これらを必ず使わなくてはならない
わけではありません。
When editing existing code which already uses one or the other set
of types, you should conform to the existing choices in that code.
これらのうちいくつかの型を使用している既存のコードを編集する場合には、
元々のコードに従ってください。
(e) Types safe for use in userspace.
(e) ユーザー空間で安全に使用するための型定義。
In certain structures which are visible to userspace, we cannot
require C99 types and cannot use the 'u32' form above. Thus, we
use __u32 and similar types in all structures which are shared
with userspace.
いくつかの構造体は、ユーザー空間でも使用されます。そのような構造体
では、C99 で定義された型や上で述べた「u32」 のような型は使用できま
せん。そのためユーザー空間と定義を共有するすべての構造体では、
「__u32」のような型を使用します。
Maybe there are other cases too, but the rule should basically be to NEVER
EVER use a typedef unless you can clearly match one of those rules.
他のケースがあるかもしれませんが、上に挙げたルールに当てはまらない場合は、
基本的に typedef を使ってはいけません。
In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should _never_ be a typedef.
一般的に、ポインタや、直接アクセスされるメンバを持つ構造体は、決して
typedef してはいけません。
Chapter 6: Functions
第６章 - 関数
Functions should be short and sweet, and do just one thing. They should
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
as we all know), and do one thing and do that well.
関数は短くて親切、かつ単純に一つのことを行いましょう。各関数は（皆が知っ
ている ISO/ANSI 画面80文字x24行で）１画面か２画面に収めましょう。一つの
関数は一つの処理に専念して、それだけをキッチリと行いましょう。
The maximum length of a function is inversely proportional to the
complexity and indentation level of that function. So, if you have a
conceptually simple function that is just one long (but simple)
case-statement, where you have to do lots of small things for a lot of
different cases, it's OK to have a longer function.
許される関数の長さは、その関数の複雑さと関数内のインデントの深さに反比例
します。本質的には単純な関数ですが、長い（けれど単純な）switch case 構文
を含む関数があったとします。たくさんの case が、それぞれで異なるちょっと
した処理を行うのであれば、関数全体が長くなっても良いでしょう。
However, if you have a complex function, and you suspect that a
less-than-gifted first-year high-school student might not even
understand what the function is all about, you should adhere to the
maximum limits all the more closely. Use helper functions with
descriptive names (you can ask the compiler to in-line them if you think
it's performance-critical, and it will probably do a better job of it
than you would have done).
あなたが複雑な関数を作成してしまい、「平凡な高校１年生では決して、この関
数の全てを理解できないだろうな」と感じたら、相手を思いやる意味での最大限
の対策を施してください。その際には、わかり易い名前の補助関数を利用してく
ださい（関数呼び出しに伴う性能低下を懸念するのであれば、コンパイラへイン
ライン展開を要求しましょう。自分でやるよりずっと上手に対処してくれること
でしょう）。
Another measure of the function is the number of local variables. They
shouldn't exceed 5-10, or you're doing something wrong. Re-think the
function, and split it into smaller pieces. A human brain can
generally easily keep track of about 7 different things, anything more
and it gets confused. You know you're brilliant, but maybe you'd like
to understand what you did 2 weeks from now.
関数内のローカル変数の数も目安となります。ローカル変数は５〜１０個にとど
めるべきもので、それを超えているようなら何か悪いことをしているのです。そ
ういう場合は関数を見直し、より細かく分割してください。一般的に、人間の脳
が余裕を持って同時に追えることは７つくらいが限界で、それ以上あると混乱し
てしまいます。自分の素晴らしさは自分が一番知っていることでしょう、がしか
し、２週間前に書いたものがすぐに分かると嬉しいとは思いませんか？
In source files, separate functions with one blank line. If the function is
exported, the EXPORT* macro for it should follow immediately after the closing
function brace line. E.g.:
ソースファイル内では、空行１行で関数を区切ってください。関数がエクスポート
されている場合、関数の終了括弧のある行のすぐ後に EXPORT* マクロを置くべきで
す。例 -
int system_is_up(void)
{
return system_state == SYSTEM_RUNNING;
}
EXPORT_SYMBOL(system_is_up);
In function prototypes, include parameter names with their data types.
Although this is not required by the C language, it is preferred in Linux
because it is a simple way to add valuable information for the reader.
関数プロトタイプ内には、データの型と一緒に、パラメータ名を含めてください。
これはＣ言語にとって、仕様上、必要ではありませんが、読み手にとって価値のあ
る情報を加える簡単な方法なので、Linux では推奨されます。
Chapter 7: Centralized exiting of functions
第７章 - 関数終了コードの共通化(goto out)
Albeit deprecated by some people, the equivalent of the goto statement is
used frequently by compilers in form of the unconditional jump instruction.
goto 構文の利用に否定的な人もいますが、コンパイラは goto 構文に等しい無
条件 jump 命令を頻繁に出力しているのです。
The goto statement comes in handy when a function exits from multiple
locations and some common work such as cleanup has to be done.
goto 構文は、関数がいくつかの場所で処理を終了してから共通的な動作（例え
ばクリーンアップ動作）を行う場合に重宝します。
The rationale is:
その論拠として以下のようなことがあります。
- unconditional statements are easier to understand and follow
- nesting is reduced
- errors by not updating individual exit points when making
modifications are prevented
- saves the compiler work to optimize redundant code away ;)
- 条件の無い文は理解しやすく、処理の流れを追うのも容易
- ネストが減る
- 修正の際、個別に実装した終了処理の一部を更新し忘れる、という誤りを予防
できる
- 冗長なコードを取り除き、最適化できるようコンパイラを手助けする
int fun(int a)
{
int result = 0;
char *buffer = kmalloc(SIZE);
if (buffer == NULL)
return -ENOMEM;
if (condition1) {
while (loop1) {
...
}
result = 1;
goto out;
}
...
out:
kfree(buffer);
return result;
}
int fun(int a)
{
int result = 0;
char *buffer = kmalloc(SIZE);
if (buffer == NULL)
return -ENOMEM;
if ( 条件文1 ) {
while ( ループ条件1 ) {
...
}
result = 1;
goto out;
}
...
out:
kfree(buffer);
return result;
}
Chapter 8: Commenting
第８章 - コメント
Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of
time to explain badly written code.
コメントは役立つものですが、コメントの付けすぎも危険なことを意識してくだ
さい。決して、コメントでプログラムの仕組みを説明しようとしてはいけません。
- どう動くかが明瞭なコードを書く方が遥かによいことです。
悲惨なコードの説明に時間を掛けることは無駄です。
Generally, you want your comments to tell WHAT your code does, not HOW.
Also, try to avoid putting comments inside a function body: if the
function is so complex that you need to separately comment parts of it,
you should probably go back to chapter 6 for a while. You can make
small comments to note or warn about something particularly clever (or
ugly), but try to avoid excess. Instead, put the comments at the head
of the function, telling people what it does, and possibly WHY it does
it.
一般的に、コメントでコードが何をしているのか(WHAT)を示そうとはしますが、
どうやっているのか（HOW）は示さないでしょう。また、関数の中にコメントを記
載することは避けましょう - 関数が複雑なので、別途に関数の説明コメントが必
要と考えるのであれば、第６章を読み直してください。「極めて巧妙なワザ（汚い
手ともいう）を使ったよ」と注意したい時にはちょっとしたコメントを付けても良
いですが、やりすぎないでください。それよりも、関数の先頭にコメントを付与し、
何をする関数なのか、さらに可能であれば、何故それをするのかまで示しましょう。
When commenting the kernel API functions, please use the kernel-doc format.
See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
for details.
カーネル API 関数へコメントを付ける場合は、kernel-doc 形式を利用してくださ
い。詳細は Documentation/kernel-doc-nano-HOWTO.txt、scripts/kernel-doc に
あります。
Linux style for comments is the C89 "/* ... */" style.
Don't use C99-style "// ..." comments.
Linux カーネルにおけるコメントスタイルは、C89 の "/* ... */" スタイルです。
C99 スタイルの "// ..." のコメントは使用してはいけません。
The preferred style for long (multi-line) comments is:
長い（複数行にわたる）コメントにとって推奨されるスタイルを次に示します。
/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
* Please use it consistently.
*
* Description: A column of asterisks on the left side,
* with beginning and ending almost-blank lines.
*/
/*
* この形式が、Linux カーネルソースコード内の複数行のコメントにお
* いて推奨されるスタイルです。
* 一貫して、それを使用してください。
*
* 説明 - 左側にアスタリスクの列を置き、開始行と終了行には、ほとん
* どなにもない行を置いてください。
*/
It's also important to comment data, whether they are basic types or derived
types. To this end, use just one data declaration per line (no commas for
multiple data declarations). This leaves you room for a small comment on each
item, explaining its use.
基本型または派生型であるかどうかに関わらず、データにコメントすることも、重
要です。そのために、（カンマを用いて、複数のデータ宣言をせず）、１行につき
１つのデータを宣言してください。そうすることで、データ毎に、使用方法を説明
する為の短いコメントを記述する余地ができます。
Chapter 9: You've made a mess of it
第９章 - 醜くしてしまったら
That's OK, we all do. You've probably been told by your long-time Unix
user helper that "GNU emacs" automatically formats the C sources for
you, and you've noticed that yes, it does do that, but the defaults it
uses are less than desirable (in fact, they are worse than random
typing - an infinite number of monkeys typing into GNU emacs would never
make a good program).
大丈夫です。失敗は誰でもするものです。たぶんあなたは長年 UNIX の使い方を
アドバイスしてくれるような先輩から、「GNU emacs」のＣソースコード自動整形
を教わってきて、それを正しいと思い込んでいたのでしょう。確かにそうなので
すが、emacs のデフォルト設定では望んだ結果にはならないのです。（実際、適
当にプログラムを打ち込むほうがまともになります - 無数のサルが延々と GNU
emacs へプログラムを打ち込んでも、決して素晴らしいプログラムは完成しませ
ん）
So, you can either get rid of GNU emacs, or change it to use saner
values. To do the latter, you can stick the following in your .emacs file:
なので、GNU emacs の利用をやめるか、設定をまともにするかのどちらかです。
設定の見直しについては、ホームディレクトリの「.emacs」ファイルに次のよう
な追記を行ってください -
(defun linux-c-mode ()
"C mode with adjusted defaults for use with the Linux kernel."
(interactive)
(c-mode)
(c-set-style "K&R")
(setq tab-width 8)
(setq indent-tabs-mode t)
(setq c-basic-offset 8))
This will define the M-x linux-c-mode command. When hacking on a
module, if you put the string -*- linux-c -*- somewhere on the first
two lines, this mode will be automatically invoked. Also, you may want
to add
(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
auto-mode-alist))
to your .emacs file if you want to have linux-c-mode switched on
automagically when you edit source files under /usr/src/linux.
これで M-x linux-c-mode コマンドが定義されます。ソースファイルの先頭２行
のどこかに、「-*- linux-c -*-」という文字列を置いておけば、ハッキングする
際に、自動的に linux-c-mode になります。また、/usr/src/linux にあるソース
ファイルを編集する場合は自動的に linux-c-mode へ切り替えたいというのであ
れば、「.emacs」ファイルに
(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
auto-mode-alist))
を加えてください。
But even if you fail in getting emacs to do sane formatting, not
everything is lost: use "indent".
emacs でまともに整形し損ねても、まだ大丈夫です - indent コマンドを使えば
救われます。
Now, again, GNU indent has the same brain-dead settings that GNU emacs
has, which is why you need to give it a few command line options.
However, that's not too bad, because even the makers of GNU indent
recognize the authority of K&R (the GNU people aren't evil, they are
just severely misguided in this matter), so you just give indent the
options "-kr -i8" (stands for "K&R, 8 character indents"), or use
"scripts/Lindent", which indents in the latest style.
GNU の indent コマンドも GNU emacs と同じ役立たずなデフォルト設定になって
いて、幾つかのコマンドラインオプションが必要になります。しかし、GNU indent
の作成者も K&R の権威を認めてはいるので、そこまでひどくはありません。
（GNU の人たちが邪悪だといっているのではなく、Ｃ言語プログラムの書式に関し
て派手に道を外してしまったということです）。indent コマンドのオプション
"-kr -i8" を指定する（これは「K&R、８文字インデント」の略）だけでもよいで
すし、最新スタイルのインデントにしたければ、"scripts/Lindent" を利用する手
もあります。
"indent" has a lot of options, and especially when it comes to comment
re-formatting you may want to take a look at the man page. But
remember: "indent" is not a fix for bad programming.
indent コマンドは多くのオプションがあるので、特にコメントを再整形する方法
に関してはマニュアルページを見るのが良いと思います。しかし、indent コマン
ドは悪いプログラムを修正するものではないということを覚えておいてください。
Chapter 10: Kconfig configuration files
第１０章 - Kconfig 設定ファイル
For all of the Kconfig* configuration files throughout the source tree,
the indentation is somewhat different. Lines under a "config" definition
are indented with one tab, while help text is indented an additional two
spaces. Example:
ソースツリー内の全 Kconfig* 設定ファイルには、少し異なるインデントルールが
あります。"config" 定義内の行に関しては、１つのタブでインデントされ、そし
て help テキストに関しては、２つの空白を追加してインデントされます。例 -
config AUDIT
bool "Auditing support"
depends on NET
help
Enable auditing infrastructure that can be used with another
kernel subsystem, such as SELinux (which requires this for
logging of avc messages output). Does not do system-call
auditing without CONFIG_AUDITSYSCALL.
Features that might still be considered unstable should be defined as
dependent on "EXPERIMENTAL":
まだ不安定かもしれないという危惧がある項目は、"EXPERIMENTAL（実験）" 段階で
あると定義されていなければなりません -
config SLUB
depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT
bool "SLUB (Unqueued Allocator)"
...
while seriously dangerous features (such as write support for certain
filesystems) should advertise this prominently in their prompt string:
そして（特定のファイルシステムに対する write サポートのように）、大変危険
な項目は、プロンプト文字列内に、はっきりとこのことを告知しなければなりませ
ん -
config ADFS_FS_RW
bool "ADFS write support (DANGEROUS)"
depends on ADFS_FS
...
For full documentation on the configuration files, see the file
Documentation/kbuild/kconfig-language.txt.
設定ファイルに関する完全なドキュメントとして、以下のファイルを参照してくだ
さい。
Documentation/kbuild/kconfig-language.txt
Chapter 11: Data structures
第１１章 - データ構造
Data structures that have visibility outside the single-threaded
environment they are created and destroyed in should always have
reference counts. In the kernel, garbage collection doesn't exist (and
outside the kernel garbage collection is slow and inefficient), which
means that you absolutely _have_ to reference count all your uses.
あるデータ構造を特定のスレッド（コンテキスト）が生成・破棄する一方で、ス
レッドの外側からも参照できる場合、そういったデータ構造には常に参照カウン
タが必要です。カーネル内部にはガーベッジコレクションが存在しません（そし
て、カーネル外部のガーベッジコレクションは低速で非効率です）。従って、利
用する全てのデータは必ず参照カウントしなければなりません。
Reference counting means that you can avoid locking, and allows multiple
users to have access to the data structure in parallel - and not having
to worry about the structure suddenly going away from under them just
because they slept or did something else for a while.
参照カウントによって、データ構造へのロックが避けられ、さらに複数ユーザー
（スレッドなどのコンテキスト）から並行して同じデータ構造へアクセスできま
す - 参照中に sleep や別の処理を行ったからといって、参照していたデータ構
造に不意にアクセスできなくなる心配は不要です。
Note that locking is _not_ a replacement for reference counting.
Locking is used to keep data structures coherent, while reference
counting is a memory management technique. Usually both are needed, and
they are not to be confused with each other.
ここで一つ注意しておきます。ロックは、参照カウンタの代わりにはなりません。
ロックは、データの一貫性を保つのに使います、一方、参照カウンタは、メモリ管
理において利用されます。通常、両方とも必要であり、互いに混同してはいけません。
Many data structures can indeed have two levels of reference counting,
when there are users of different "classes". The subclass count counts
the number of subclass users, and decrements the global count just once
when the subclass count goes to zero.
実は多くのデータ構造は、異なる "class" のユーザーを持つ場合において、２段
階の参照カウンタを持っています。subclass カウンタは subclass ユーザー数を
カウントし、カウンタが０になった場合に限ってグローバルカウンタをデクリメ
ントします。
Examples of this kind of "multi-level-reference-counting" can be found in
memory management ("struct mm_struct": mm_users and mm_count), and in
filesystem code ("struct super_block": s_count and s_active).
この多段階の参照カウンタの例が、メモリ管理に見受けられます（mm_struct
構造体の mm_users と mm_count です）。ファイルシステムのコードにも見受けら
れます（super_block 構造体の s_count と s_active です）。
Remember: if another thread can find your data structure, and you don't
have a reference count on it, you almost certainly have a bug.
覚えておいてください - 別のスレッドがあなたのデータ構造を探すことができる
のに、あなたはそのデータ構造に参照カウンタを持っていないとすると、ほぼ確
実にバグを引き起こします。
Chapter 12: Macros, Enums and RTL
第１２章 - マクロ、列挙型および RTL
Names of macros defining constants and labels in enums are capitalized.
定数を定義するマクロの名前と列挙定数は大文字で記述します。
#define CONSTANT 0x12345
Enums are preferred when defining several related constants.
列挙型は複数の関連する定数を定義するときに好んで利用されます。
CAPITALIZED macro names are appreciated but macros resembling functions
may be named in lower case.
マクロは大文字が好ましいですが、関数形式マクロは小文字でも構いません。
Generally, inline functions are preferable to macros resembling functions.
一般的に、関数形式マクロよりもインライン関数の方が望ましいでしょう。
Macros with multiple statements should be enclosed in a do - while block:
複数の文から構成されるマクロは do - while ブロックで囲むべきです。
#define macrofun(a, b, c) \
do { \
if (a == 5) \
do_this(b, c); \
} while (0)
Things to avoid when using macros:
マクロ使用時に避けるべきこと -
1) macros that affect control flow:
1) 制御の流れに影響を与えるマクロ -
#define FOO(x) \
do { \
if (blah(x) < 0) \
return -EBUGGERED; \
} while(0)
is a _very_ bad idea. It looks like a function call but exits the "calling"
function; don't break the internal parsers of those who will read the code.
このマクロは非常に悪いアイデアです。関数呼び出しのように見えながら、「呼
んだ」関数から抜けてしまいます - コードを読む人々の頭の中のパーサを壊して
はいけません。
2) macros that depend on having a local variable with a magic name:
2) 特定の名前のローカル変数に依存しているマクロ
#define FOO(val) bar(index, val)
might look like a good thing, but it's confusing as hell when one reads the
code and it's prone to breakage from seemingly innocent changes.
このマクロは良いことのように見えるかもしれませんが、誰かがコードを読む際
に地獄のように混乱させるし、表面上、問題の無い変更が処理を壊す傾向にあり
ます。
3) macros with arguments that are used as l-values: FOO(x) = y; will
bite you if somebody e.g. turns FOO into an inline function.
3) 左辺値として使われる引数付マクロ - FOO(x) = y - 例えば、もし誰かがこの
マクロをインライン関数に変更しようとすれば文句を言われるでしょう。
4) forgetting about precedence: macros defining constants using expressions
must enclose the expression in parentheses. Beware of similar issues with
macros using parameters.
4) 演算子の優先度について忘れること - 式で定数を定義するマクロは式を括弧で
囲まなければなりません。引数を利用するマクロの同じような問題に用心しまし
ょう。
#define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3)
The cpp manual deals with macros exhaustively. The gcc internals manual also
covers RTL which is used frequently with assembly language in the kernel.
マクロの詳細については cpp マニュアルを参照してください。カーネルの中でア
センブリ言語と供によく利用される RTL については gcc インターナルマニュアル
を参照しましょう。
Chapter 13: Printing kernel messages
第１３章 - カーネルメッセージの表示
Kernel developers like to be seen as literate. Do mind the spelling
of kernel messages to make a good impression. Do not use crippled
words like "dont"; use "do not" or "don't" instead. Make the messages
concise, clear, and unambiguous.
カーネル開発者は教養人のように見られたいものです。良い印象を与えるカーネル
メッセージの綴り方に気を使ってください。"dont" のような壊れた言葉は使って
はいけません。"do not" か "don't" を代わりに使いましょう。メッセージは簡潔
で明確かつ明白なものにしましょう。
Kernel messages do not have to be terminated with a period.
カーネルメッセージはピリオドで終える必要はありません。
Printing numbers in parentheses (%d) adds no value and should be avoided.
括弧つきの数字 (%d) を表示することは価値が無いし避けるべきでしょう。
There are a number of driver model diagnostic macros in <linux/device.h>
which you should use to make sure messages are matched to the right device
and driver, and are tagged with the right level: dev_err(), dev_warn(),
dev_info(), and so forth. For messages that aren't associated with a
particular device, <linux/kernel.h> defines pr_debug() and pr_info().
<linux/device.h> には、メッセージが適切なデバイスとドライバに合致し、適切
なレベル: dev_err(), dev_warn(), dev_info(), その他、にタグ付けられている
ことを確認するのに使う数多くのドライバモデル診断マクロがあります。特定のデ
バイスに関連しないメッセージの為に、<linux/kernel.h> では、pr_debug() と
pr_info() を定義しています。
Coming up with good debugging messages can be quite a challenge; and once
you have them, they can be a huge help for remote troubleshooting. Such
messages should be compiled out when the DEBUG symbol is not defined (that
is, by default they are not included). When you use dev_dbg() or pr_debug(),
that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG.
A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
ones already enabled by DEBUG.
良いデバッグ用メッセージを考え出すことは、非常に難しい - そして、いったん
それができれば、リモートトラブルシューティングにおいて非常に大きな助けにな
るでしょう。そのようなメッセージは DEBUG シンボルが定義されていない時には
取り除かれるべきです。（デフォルトで DEBUG シンボルは含まれていません）。
あなたが、dev_dbg() や pr_debug() を利用するとそれは自動的に行われます。多
くのサブシステムでは -DDEBUG を有効にする Kconfig オプションを持っています。
関連するしきたりとしては、DEBUG で有効になったものに加え、dev_vdbg() メッ
セージを追加する VERBOSE_DEBUG を使います。
Chapter 14: Allocating memory
第１４章 - メモリ確保
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
documentation for further information about them.
カーネルは次の汎用メモリアロケータを提供します - kmalloc(), kzalloc(),
kcalloc(), および vmalloc()。これらについての更に詳しい詳細については API
ドキュメントを参照してください。
The preferred form for passing a size of a struct is the following:
好ましい構造体サイズの渡し方は次のものです。
p = kmalloc(sizeof(*p), ...);
The alternative form where struct name is spelled out hurts readability and
introduces an opportunity for a bug when the pointer variable type is changed
but the corresponding sizeof that is passed to a memory allocator is not.
これの代わりに構造体型の名前を記述する渡し方をすると、読みにくい事に
加え、ポインタ変数の型を変更した場合、メモリアロケータに渡すサイズが対応
しないバグの温床にもなります。
Casting the return value which is a void pointer is redundant. The conversion
from void pointer to any other pointer type is guaranteed by the C programming
language.
void ポインタで返された返却値をキャストすることは冗長です。void ポインタ
から他のポインタ型への変換はＣ言語によって保証されています。
Chapter 15: The inline disease
第１５章 - インライン病
There appears to be a common misperception that gcc has a magic "make me
faster" speedup option called "inline". While the use of inlines can be
appropriate (for example as a means of replacing macros, see Chapter 12), it
very often is not. Abundant use of the inline keyword leads to a much bigger
kernel, which in turn slows the system as a whole down, due to a bigger
icache footprint for the CPU and simply because there is less memory
available for the pagecache. Just think about it; a pagecache miss causes a
disk seek, which easily takes 5 miliseconds. There are a LOT of cpu cycles
that can go into these 5 miliseconds.
gcc は、「私を速くして」という魔法、"inline" と呼ばれる高速化オプションを
持っているという共通の誤認識があります。inline の使用が適切である場合もあ
りますが(例えば、マクロを置き換える場合、１２章参照)、そう頻繁にはありませ
ん。inline キーワードを頻繁に利用するとカーネルは大きくなります。これによ
り CPU の命令キャッシュのヒット率が低下し、キャッシュフットプリントが増加
します。また、単純にページキャッシュとして使用できるメモリが減ります。これ
らの要因によって、システム全体が遅くなります。これについて考察してみましょ
う - ページキャッシュミスは容易に５ミリ秒かかるディスクのシークを発生させ
ます。この５ミリ秒の中には（様々な処理を行うことができる）多くの CPU 周期
を入れることができるのです。
A reasonable rule of thumb is to not put inline at functions that have more
than 3 lines of code in them. An exception to this rule are the cases where
a parameter is known to be a compiletime constant, and as a result of this
constantness you *know* the compiler will be able to optimize most of your
function away at compile time. For a good example of this later case, see
the kmalloc() inline function.
だいたいの経験則では４行以上の関数はインライン関数にしないことです。この
規則の例外は、引数がコンパイル時に定数であることがわかっている場合と、そ
れに伴いコンパイラの最適化によって関数の大部分が削除されると分かっている
場合です。例えば、後者の良い例が kmalloc() インライン関数でしょう。
Often people argue that adding inline to functions that are static and used
only once is always a win since there is no space tradeoff. While this is
technically correct, gcc is capable of inlining these automatically without
help, and the maintenance issue of removing the inline when a second user
appears outweighs the potential value of the hint that tells gcc to do
something it would have done anyway.
人々はよく、static で一回しか利用されない関数をインライン関数にするのは常
にうまくいくと主張します。なぜならサイズを犠牲にしないからです。これは技術
的には正しいのですが、gcc は助け無しに自動的にインライン関数にすることが可
能ですし、二回利用されるようになった時に inline を外さなければならない手間
を考えると、gcc がどうせ実行することに対してヒントを与えるのは、それほど潜
在的価値のないことでしょう。
Chapter 16: Function return values and names
第１６章 - 関数の返却値と名前
Functions can return values of many different kinds, and one of the
most common is a value indicating whether the function succeeded or
failed. Such a value can be represented as an error-code integer
(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
non-zero = success).
関数は多くの異なる種類の値を返すことができ、最もありふれたの値の一つは関
数が成功したか失敗したかをを示す値です。そのような値はエラーコードの整数
値(-Exxx = 失敗、0 = 成功)か、「成功したかどうか」を表す boolean（0 = 失
敗、0 以外 = 成功)で表現されます。
Mixing up these two sorts of representations is a fertile source of
difficult-to-find bugs. If the C language included a strong distinction
between integers and booleans then the compiler would find these mistakes
for us... but it doesn't. To help prevent such bugs, always follow this
convention:
この二つの表現が混在したソースには、見つけることの難しいバグが豊かに実り
ます。もしＣ言語が整数型と boolean 型を明確に区別してくれるなら、コンパイ
ラは私達のためにこれらのミスを見つけてくれるでしょう...しかし区別してくれ
ません。このようなバグを防ぐには、常に次のしきたりに従うことです -
If the name of a function is an action or an imperative command,
the function should return an error-code integer. If the name
is a predicate, the function should return a "succeeded" boolean.
もし関数の名前が動作か命令的な指示だったらその関数はエラーコード
として整数を返すべきです。もし名前が述部(条件の真偽を判定するよう
なもの)であればその関数は成功したかどうか」を表す boolean を返す
べきです。
For example, "add work" is a command, and the add_work() function returns 0
for success or -EBUSY for failure. In the same way, "PCI device present" is
a predicate, and the pci_dev_present() function returns 1 if it succeeds in
finding a matching device or 0 if it doesn't.
例えば、"add work" は指示であり、そして add_work() 関数は成功時に０を返す
か、失敗時に -EBUSY を返します。同じように、"PCI device present" は述部で
あり、そして pci_dev_present() 関数は、対応するデバイスを見つけられたら、
１を返し、見つけられなかったら０を返します。
All EXPORTed functions must respect this convention, and so should all
public functions. Private (static) functions need not, but it is
recommended that they do.
全てのエクスポートされた関数はこの規約に従っており、全ての公開された関数
はそうすべきです。プライベート(static)関数はその必要が無いが、そうするこ
とが推奨されます。
Functions whose return value is the actual result of a computation, rather
than an indication of whether the computation succeeded, are not subject to
this rule. Generally they indicate failure by returning some out-of-range
result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure.
処理が成功したかどうかではなくて、計算の実結果を値として返す関数は、この
規約の対象ではありません。一般的に、これらの関数は範囲外の結果を返すこと
で失敗を示します。典型的な例は、ポインタを返す関数です - これらは NULL
か ERR_PTR によって、失敗を報告します。
Chapter 17: Don't re-invent the kernel macros
第１７章 - カーネルマクロを再発明しないでください
The header file include/linux/kernel.h contains a number of macros that
you should use, rather than explicitly coding some variant of them yourself.
For example, if you need to calculate the length of an array, take advantage
of the macro
include/linux/kernel.h ヘッダファイルには、明らかにあなた自身がその変種を
コーディングするよりも、あなたが使うべき数多くのマクロを含んでいます。例えば
あなたが配列の長さを計算する必要があるなら、以下のマクロを上手く利用してくだ
さい。
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
Similarly, if you need to calculate the size of some structure member, use
同様に、もしあなたが構造体メンバのサイズを計算する必要があるなら、次のマク
ロを利用してください。
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
There are also min() and max() macros that do strict type checking if you
need them. Feel free to peruse that header file to see what else is already
defined that you shouldn't reproduce in your code.
他にも、必要なら厳密な型チェックを行う min() と max() マクロもあります。
既に定義されているものをご自身のコードで再作成しないように、ヘッダーファイ
ルを熟読してください。
Chapter 18: Editor modelines and other cruft
第１８章 - エディタのモードラインやその他の書き換え
Some editors can interpret configuration information embedded in source files,
indicated with special markers. For example, emacs interprets lines marked
like this:
エディタの中には、ソースファイル中に埋め込まれた設定情報を解釈できるものが
あります。例えば、Emacs はこのようにマークされた行を解釈します。
-*- mode: c -*-
Or like this:
もしくは、このような。
/*
Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
End:
*/
Vim interprets markers that look like this:
Vim は次のようなマーカーを解釈します。
/* vim:set sw=8 noet */
Do not include any of these in source files. People have their own personal
editor configurations, and your source files should not override them. This
includes markers for indentation and mode configuration. People may use their
own custom mode, or may have some other magic method for making indentation
work correctly.
これらをソースファイルに含めないでください。人々は自分の個人的なエディタの
設定を持っており、あなたのソースファイルはそれを上書きすべきではありません。
これはインデントやモード設定の為のマーカーを含んでいます。人々は自分の設定
モードを使うか、正しくインデントするような上手な手段を持っているでしょう。
Appendix I: References
付録 I - 参考文献
The C Programming Language, Second Edition
by Brian W. Kernighan and Dennis M. Ritchie.
Prentice Hall, Inc., 1988.
ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
URL: http://cm.bell-labs.com/cm/cs/cbook/
プログラミング言語Ｃ 第２版 ANSI 規格準拠
Brian W. Kernighan, Dennis M. Ritchie 著 / 石田晴久訳
共立出版 1989
ISBN 4-320-02692-6
URL: http://cm.bell-labs.com/cm/cs/cbook/
The Practice of Programming
by Brian W. Kernighan and Rob Pike.
Addison-Wesley, Inc., 1999.
ISBN 0-201-61586-X.
URL: http://cm.bell-labs.com/cm/cs/tpop/
プログラミング作法
Brian W. Kernighan, Rob Pike 著 / 福崎俊博訳
アスキー 2000
ISBN 4-7561-3649-4
URL: http://cm.bell-labs.com/cm/cs/tpop/
GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
gcc internals and indent, all available from http://www.gnu.org/manual/
GNU マニュアル - K&R とこのテキストに従って - cpp, gcc, gcc internals と
indent コマンド, 全ては http://www.gnu.org/manual/ にあります。
WG14 is the international standardization working group for the programming
language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
WG14 はプログラミング言語Ｃのための国際標準化会議です。
URL: http://www.open-std.org/JTC1/SC22/WG14/
Kernel CodingStyle, by greg@kroah.com at OLS 2002:
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
--
Last updated on 2007-July-13.
Linux カーネル 2.6 付属文書一覧へ戻る