アナログCPU:5108843109

ゲームと音楽とプログラミング(酒と女とロックンロールのノリで)

('ω') < イザユケエンジニャー

コメントの書き方

会社で、if構文でのコメントの書き方について少し話題になったので書いておく。
コード例はPHPですが別にどの言語でも変わらないはず。

①ifの前にフル説明

// hogeの値が1の場合、trueを返す
if ($hoge == 1)
{
    return true;
}

②ifの説明と中身の説明を分ける その1

// hogeの値が1の場合
if ($hoge == 1)
{
    // trueを返す
    return true;
}

③ifの説明と中身の説明を分ける その2

// hogeの値をチェック
if ($hoge == 1)
{
    // 1であればtrueを返す
    return true;
}

④ifの中にフル説明

if ($hoge == 1)
{
    // hogeの値が1の場合、trueを返す
    return true;
}

まあ別にどれが正解ってわけではないですし場合によるのではって感じの身も蓋も無い結論になったのですが。
あくまでコメントは分かりやすくするためのものなので、コーディング規約的に決めるものでもないかなと。(決めたとおりに書いたらかえって分かりにくいケースもあるはず)

この例で言うと②は好きではないです。
(「○○の場合」って書かれると、その下の処理がその場合に行われるように見える)


もうちょっと複雑なとき、わたしがきっちりコメントを書くとしたら↓のような感じですかね。
普段なら、1行目のは省略することが多い、というところ。
上の②のパターンだと、elseの前にコメントが挟まっても省略されても読みづらい気が。

// hogeとfugaの値によって処理を変える
if ($hoge == 1 && $fuga == true)
{
    // hogeが1、fugaがtrueの場合:正常
    return 0;
}
elseif ($hoge == 2)
{
    // hogeが2の場合:warning
    return 1;
}
else
{
    // 上記以外の場合:エラー
    return -1;
}