コメントのつけ方

[しいさ]

コードのことではなくて、ここで質問してよいのか割らないのですが、なんでも質問ということで質問させていただきます><

現在は学生で企業へ提出するためのゲームを制作中で、それのコメントのつけ方で悩んでいます。
具体的には、だれを対象にコメントを書けばよいのかということろです。

変数につけるのはわかります。
ですが機能を使っているところで、例えばfor文を使って

コード:

int map_height = 10; // マップの高さ

for (int y = 0; y < map_height; ++y) {
                   //処理
}

とあったとします。

この時に対象がプログラマであればfor文は簡単な機能であり、説明はいらないかと思います。
ですが、対象がプログラマ以外であればfor文が何をするのかわからないかもしれず、
// マップの高さ文繰り返す
とでも書いたほうが良いかとも思います。

回答よろしくお願いします。

[Dixq (管理人)]

現場では度々コメントの書き方としてDoxygenフォーマットで記載されることがあります。
http://www.doxygen.jp/
また、コメントが多数無いと理解できないコードは、書き方が悪い場合が多いです。
多くの場合は関数ヘッダにだけコメントを書けば内部の処理に一行一行コメントを書く必要はないはずです。
もし分かりにくい処理があるのであれば、それは何をしているのか分かり易いメソッドに分ける・分かり易い変数名を付けるなどの工夫ができるはずです。

従って、関数ヘッダに関数ごとにdoxygen形式でコメントを書き、実装内部にコメントを書く場合は、
コメントが無いと分かりにくい場合のみとするというルールがよいかと思います。
コメントが大量にあると逆に読みにくいです。

[しいさ]

私が機能単位で見ていたので少し視点がずれていたように思えました。

簡単、難しいということではなく、その機能の中の処理内容で見ればよいのですね。

大変勉強になりました。

Doxygenもしばしば聞くので少し勉強してみます。

[Dixq (管理人)]

変数名の付け方として良くない代表例としてよく言われるのがflagです。
既存コードとしてこういう分かりにくい変数が使われていると仮定し、
今、m_flagがfalseなら中身が空っぽであることを意味しているとしましょう。

コード:

bool m_flag = false;

void hoge(){
    if(m_flag==false){
        doProc();
    }
}

これだと一見何をしているのかよくわかりません。
これを分かり易いメソッド名を付けて分かり易くしてみましょう。

コード:

bool m_flag = false;

bool isEmpty(){
    return m_flag==false;
}

void hoge(){
    if(isEmpty()){
        doProc();
    }
}

これだけでも随分意味は分かり易くなりました。
ここにdoxygen形式のコメントを入れてみます。

コード:

bool m_flag = false; //! 中身が空っぽであればfalseを意味する変数

/*!
 @brief 中身が空っぽであればtrueを返す
 @retval true : 中身が空っぽである
 @rerval false : 中身が空ではない
*/
bool isEmpty(){
    return m_flag==false;
}

void hoge(){
    if(isEmpty()){
        doProc();
    }
}

このように書けば十分でありましょう。
関数の中に一行一行コメントを書かないといけないケースに出くわしたらそれはリファクタリングできるケースである場合が多いです。
細かいアルゴリズムの計算などの場合書く必要があるケースはありますが、一行単位のコメントは必要最小限でよいかと思います。
Doxygen形式で書いておけば仕様書を自動生成できるので便利です。
時間のない会社員の見方と言えます。