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