C/C++: 2008年1月アーカイブ

C++でも自動でドキュメント生成してくれるツールあるに決まってるよなってことで、調べたら、Doxygenっていのが一般的っぽいんで、これを使うことにした。ヘッダコメントとかもDoxygen対応の書式にした。

インストールしたら、DoxywizardってGUIのツールができるから、これ使ってちょっと設定変えて、[Start]ボタン押すだけでドキュメントが生成できた。

コメントの書き方は、QtスタイルとJavaDocスタイルがあるけど、自分はJavaDocスタイルに慣れてるからこれを使うことにした。

設定をいじったとこは、

• [OUTPUT_LANGUAGE]をJapaneseへ
• [INPUT_ENCODING]をShift_JISへ
• privateメンバを表示するように、[EXTRACT_PRIVATE]を有効へ
• コメント1行目の概要を表示するように、[JAVADOC_AUTOBRIEF]を有効へ
• ファイル一覧でフルパスが表示されないように、[FULL_PATH_NAMES]を無効へ

ってとこかな。

で、ヘッダコメントは↓こんな感じにした。

• ファイルヘッダ

/**
 * @file Di.h
 *
 * @brief DirectInput処理
 *
 * @author 1122
 * @date 2008/01/18
 */

• クラスヘッダ

/**
 * DirectInput処理
 *
 * @author 1122
 * @date 2008/01/18
 */

• 関数ヘッダ

/**
 * DirectInput初期化
 * 
 * @param[in] a_hWnd ウィンドウハンドル
 * @param[in] a_hInstance インスタンスハンドル
 * 
 * @return 処理結果
 * @retval true 成功
 * @retval false 失敗
 */

前にC++で作ってたゲームが久々気になり、ソースコードを眺めてた。そしたらそのコードにイライラしてきたので、リファクタリングを始めた。

学生の頃に作ったコードだから、もちろんコーディング規約を作ってるわけはなく、暗黙の了解という感じでコーディングの仕方をそろえてた。それで何となくは規則性のあるコードが書かれてたけど、ただ規則的なだけで、わかりにくい記述がいくつかあった。そんで、まずは規約を作ってみた。

関数のヘッダコメントも規約として決めた。
↓例えばこんなん。

//----------------------------------------------------------
// Name   : Init
// Desc   : 初期化
//
// Arg    : [in]  int  a_nIn   : 入力値
//          [out] int* a_pnOut : 出力値
//
// Return : int nRet : 戻り値
//----------------------------------------------------------

引数のとこを"Arg"にするか"Param"にするかというどーでもいいことで悩んだ。自分としては"Param"って書いた方がパッと見わかりやすい。ただね、今回作った規約では、変数名はハンガリアン記法ってことにしてある。ハンガリアン記法だと、引数のプレフィクスは"a_"が一般的。で、この"a_"っつーのは、Argumentの頭文字。そうすると、引数の説明は"Arg"にしないと統一感ねーよな…、となり、散々悩んで、"Arg"に決定。こういうとこでも優柔不断全開。

JavaDocとかphpDocumentorみたいに、C++ Docとかいうのがあればなぁ。。。

ハンガリアンなんだけど、これは元々嫌いだったんだけど、仕事で使ってみたら、コード理解しやすいってことがわかり、なるべく使うようにしてる。