プログラムへの効果的なコメントの書き方

プログラミングへの効果的なコメントルールについて考えます。通常のコメントからファイルへのコメント、関数へのコメントなど様々なコードに対するコメントを定義します。ここでは、Doxygenをベースとしたコメントルールについて解説していきます。

01: 通常のコメント

// 処理1
int a = 10 // コメント

// 処理2
int b = 20 // コメント
int c = 30 

02: ファイルへのコメント

/**
 * <説明文>
 * @file <ファイル名>
 * @author <作成者>
 * @date <日付>
 */

03: 関数へのコメント

## 戻り値が1つの場合 ##
/**
 * <説明文>
 * @param[in] arg1 <引数の説明>
 * @param[in] arg2 <引数の説明>
 * @return <戻り値の説明>
 * @attention <注意喚起>
 * @warning <警告>
 * @note <メモ>
 * @bug <バグ>
 */
int func(int arg1, int arg2) {
## 戻り値/引数の値が複数の場合 ##
/**
 * <説明文>
 * @param[in] arg1 <引数の説明:1行目>
 * <引数の説明:2行目>
 * @param[in] arg2
 *  @arg 引数の値1 <説明>
 *  @arg 引数の値2 <説明>
 * @retval true <戻り値の説明>
 * @retval false <戻り値の説明>
 */
boolean func(int arg1, int arg2) {

04: 変数へのコメント

//! <説明文>
int hoge = 0

05: if文へのコメント

if error != nil { // ダウンロードが失敗した場合
    print("ダウンロードが失敗しました")
    print(error)
} else { // ダウンロードが完了した場合
    print("ダウンロードが完了しました")
}

06: assert文へのコメント

## 事前条件 ##
/** @pre szは1〜MAXBUFの範囲内にあること。**/
assert(0 < sz && sz <= MAXBUF)

## 事後条件 ##
/** @post メモリ割り当ては常に成功する。**/
assert(p != NULL);

07: enum文へのコメント

/** 曜日 **/
enum  {
    Sun,   /**< 日曜 **/
    Mon,   /**< 月曜 **/
    Tues,  /**< 火曜 **/
}

08: 空行について

下記文の前に空行を入れる。

  • if文
  • for文

下記文の後に空行を入れる。

  • //でコメントアウトされた文