この文書の意図
==============
AirOneのコーディングスタイルを定めます。
従いたくないルールがある場合、ルールを破るのではなく、議論をしてコーディングスタイル自体を変更するようにしてください。


用語の定義
==========
プロジェクト: 実行ファイル、またはライブラリを作るファイル一式。
通常、CVS上では、この単位で管理します。
モジュール: C言語の場合、ファイルのこと。



重要
====
スタイルに関して非常に強いこだわりがある場合、プロジェクト管理者がこのコーディングスタイルに従わないことを認めます。
その場合、次の義務が発生します。
1. 新しいコーディングスタイルに関する文書を作成すること
2. プロジェクト内でスタイルを一貫すること(混在は認めません)
3. 他の開発者からemacs用の設定lispを求められた場合、すみやかに提供すること
4. 「コメントを英語で書く」のルールだけは従うこと



ファイル構成
============
ソースファイル
--------------
ファイル名は全て小文字にします。
単語を区切りたい場合は、-(ハイフン)を使ってください(e.g. foo-util.c)。

改行コードは、LF(Unix改行)が望ましいですが、別の改行コードでもよいです。
ひとつのプロジェクト内で、混在を避けてください。


ドキュメントファイル
--------------------
改行コードに関しては、ソースファイルに従ってください。
文字コードは、ひとつのプロジェクト内で統一されていれば、何でもよいです。


ディレクトリ構成
----------------
理由がない限り、あまり奇抜なディレクトリ構成はしないでください。
既存のプロジェクトを参照して、なるべく従うように努力してください。

次の構成を必須とします。
* プロジェクトのトップディレクトリにソースファイルは置かない。
* srcディレクトリを作成して、ソースファイルはそのディレクトリ以下に置く。
サブディレクトリの構成は自由。
* docディレクトリを作成して、ドキュメントファイルはそのディレクトリ以下に置く。
サブディレクトリの構成は自由。

細部は、プロジェクト管理者の裁量に任せます。



ソース
======
インデント、カッコの位置
------------------------
apacheのインデントに従います(タブ文字の扱いを除く)。
(CVS:/airone-doc/fyi/emacs-styleファイル参照)。

fyi: 事実上、Linuxのソースと同じスタイルです。
(Linux配布のDocumentation/CodingStyleファイルのChapter1,2参照)。


インデントは、タブ文字ではなくスペース文字を使います。
.emacs.elに下記の行を追加してください。
(setq-default indent-tabs-mode nil)

注意:
歴史的な理由で、古いソースコードは、インデントにタブ文字(タブ幅8)を使っています。


名前規約
--------
変数名、関数名は小文字のみにしてください。
(Linux配布のDocumentation/CodingStyleファイルのChapter3参照)。

次の例外を認めます。
外部モジュールの名前規約が異なる場合(e.g. LikeThis)、そのモジュールとのインターフェース部分に関しては、そのモジュールに合わせても良いです。

プリプロセッサのマクロは全て大文字にしてください。
enum列挙型の変数名は全て大文字にしてください。
constで定義した定数の変数名は大文字が望ましいです(これは例外を認めます)。

型名は、大文字小文字の混合(e.g. LikeThis)、または全て小文字で_tを付ける(e.g. likethis_t)ようにしてください。

ライブラリの外部に見えるシンボル名は、固有のprefixをつけてください(e.g. soma_foo)。

モジュール(ファイル)から外に見えるシンボルも、モジュール毎のprefixをつけることが望ましいです。
規模や性質にもよるので、例外を認めます。


コメント
--------
コメントは英語のみです(ローマ字も不可)。
日本語で説明(言い訳)を書きたい場合、ソースコードと別のドキュメントファイルを作成してください。

以下のコメントは重要です。
* モジュールの説明
* 関数の説明
* 型の説明
* ローカル以外の変数の説明
* 定数の説明
* 言い訳コメント


グローバル関数の説明は次のようなapacheスタイルに従ってください。
例
/**
* Allocate memory.
* @param size The size in byte of memory to allocate.
* @return A pointer to the allocated memory.
* @remark Wrapper of malloc(3)
* @see aru_free()
* @tip Don't use malloc(3) directly.
* @warning Use aru_free() for allocate memory by aru_malloc().
*/
void* aru_malloc(size_t size)

コメント内でシンボルを参照する時は、以下のGNOMEスタイルを使ってください。
@name: reference to a parameter.
%name: reference to a constant.
name(): function reference.


ロジックへのコメントは(基本的に)不要です。
(Linux配布のDocumentation/CodingStyleファイルのChapter5参照)。

CソースでのC++風のコメント(//...)は、開発初期では許可します。
最終的には無くすようにしてください。


言い訳コメント
--------------
次のような場合、言い訳コメントを極力書くようにしてください。
(カッコ)内は例。

* 潜在的なバグを自分で認識している場合(後で直す予定)
(// XXX: buggy. to be fixed)
* コードが汚いことを自分で認識している場合
(// ugly)
* パフォーマンスやコーディング上の都合で、ハック的なコードの場合
(// hack)
* その他、自分で問題を認識している場合

言い訳コメントは簡単でほとんど意味不明でも構いません。
言い訳コメントの一番の目的は、コードレビューする相手に対し、「自分が問題を認識していること」を伝えることです。



その他の表記
------------
ポインタ型変数の定義は次のどちらでも可とします。
int *p;
int* p;

typedefしている構造体のタグ名はどうでもよいです。
e.g.
typedef struct _Foo Foo;
typedef struct Foo Foo;

関数の仮引数のインデントはどうでもよいです。
e.g.
int func(int a, int b)
int func(int a,
int b)


その他(表記以外)
----------------
C言語でもinlineは使用してよいです。
(サポートしていない環境では、プリプロセッサで消せるので)

モジュール内privateなシンボル(変数、関数)は、staticで宣言、定義することを強く推奨します。

ライブラリはMT-safeにしてください。
できない場合、その関数のコメントにMT-safeでないことを明記してください。