調べ物した結果

現役SEが仕事と直接関係ないことを調べた結果とか感想とか

IFのコメント外にかく?中にかく?

Ifはお好きですか。


If文好きですか。私はどちらかというと嫌いです。
憎んではいませんが、なるべく見えないところに潜んでいてほしいと願っています。
何の話かというと「if文のコメントって外側に書くの、内側に書くの?」
というような話がチーム内でて、私なりに腑に落ちた解釈がようやくできたの記事に起こすか。というところ。ちなみに言語はC#です。
主観オブ主観だけど。

// 外側
if (value >= 3)  // vb.net使ってた時はここに書いてた気もする。
{
   // 内側
}

こーゆーやつ。今までは何となくニュアンスで使い分けてたような気がする。もう今となっては今までどうやってたかわからない。

私は両方かく。


冒頭の通り、私は外側にも内側にもコメントを書く。コメントの内容によりけり。ということだ。
あたりまえなんだろうけど。

外側に書くとき


両方にかく。とか言っておきながら実は外側に書くケースは少ないと思っている。

例1:

//  valueが3以上の場合。
if (value >= 3) 
{
   // 内側
}

このコメントがあってもなくてもなーんの役にもたたないと思っているので、こーゆーコメントは極力残さないようにしている。
「じゃぁ、もうちょっと複雑になったらなかったら困るやろがい!」という声が聞こえるきがするので複雑化してみる。
値ももう少し具体性をだす。
例2:

//  表示中かつ期間内でアイテムタイプが3か2の場合
if ( IsVisible() && InTerm(date1, date2) && (ItemType == 3 || ItemType == 2)  ) 
{
   // 内側
}

ぎりぎり、有効に見えてきたか?いやこれ日本語みても「結局それでどーゆーこと?」ってなって内側のソース見ることになるよね?ということは
「~場合」というのは内側の処理の説明。
だから、これ書くとしても内側においとこーね。となる。

そもそも、こんな入り組んだ条件メソッドに別だしして適切なメソッド名おいてもらったほうがいいまである。
それだと

//  表示中かつ期間内でアイテムタイプが3か2の場合
if ( IsVisible() && InTerm(date1, date2) && (ItemType == 3 || ItemType == 2)  ) 
{
   // 内側
} elseif()
{}
elseif()
{}
elseif()
{}
elseif()
{}
else
{}

というような地獄が来た時にやっぱりつらいので、メソッド化だけでは耐えきれないこともあるだろうから内側に場合を書くのは有効と思う。
ということで、
ifの外側はほかのコメントと同様に、処理が入り込んだ理由を書くべきかな。

//  表示中の商品名を取得したいから判定をする。
if ( IsVisible() && InTerm(date1, date2) && (ItemType == 3 || ItemType == 2)  ) 
{
   // 内側
}

こんな感じか。正直適当にロジックかいたからコメントも適当だけど。
少なくともifが生まれてしまった経緯を伺うことができるので、これならないよりあってもいいかな。と思う。
他のコメントと同じなら各頻度少なくないんじゃないの?という疑問があるかもしれない。
上にも書いたが基本的にifは条件式をそのまま書くとわかりにくいので説明変数に入れたりメソッドに切り出したりで何の判定かとか、
何の意図があってのことか。ということはそっちに書いてあることが多いので、わざわざ外側に書くまでもないことのほうが多いから、少ない。とした。

内側は?


内側は。内側の説明を書きたければどうぞ。といった感じ(急に雑)
複雑ならクラスなりメソッドなりにブロック毎置き換えたほうが見やすいだろうから、こっちも正直そこまでコメントが出る幕がないのでは。
どっちも書くといったり書かないと言ったりどっちなんだ。結局はっきり煮え切らないじゃないか。

まとめ


・ifの外側はif文そのものを書く理由を書く。
・ifif祭り等で苦しい時は内側に「~の場合」を書く。
・コメントを書く前にメソッド名等で表現できないか、振り返る(コードの説明を書いてるときは大体赤信号)
どちらかというとコメントを書かなくてもいい理由を探して適当言ってるだけかもしれない。
個人的にはコメントあるとコメントだけ読んでコード見落としたりするんだよな。ただの怠けかもしれんが。