スタッフBLOG

おはようございます。本日の当番、プログラマーのL.A.です。

最近、天気がちょうどよくなってきたと思います。現在大阪の温度は80.6°です。

あっ、そうか。日本であれば、温度について話す時は摂氏で言いますね。実は私の
出身地はアメリカなので、稀に摂氏を使うのを忘れてしまいます。

早速ですが、私はプログラマーですので、この温度単位を変換する手順をC++で
書きたいと思います。

float tc(float in)
{
　　　　float out;

　　　　out = (in - 32.f) * 5.f / 9.f;

　　　　return out;
}

ああぁ、これで変換することが少し楽になった気がします。しかし、このソースを
見ると、何かがヌケテいるじゃないですか？

セミコロン？

いいえ。

型変換キャスト？

いいえ、違います。

抜けているの箇所は大事なんですよぉ！

そうです。コメントです。コメントについて少し話せて頂きたいと思います。

---L.A.'s　トップ３ コメント　ルール---

① まずは、コード自体を読みやすくなるように書くこと。先ほど書いたソースを
書き直したら、こうになりますが、どうでしょうか。

float temperature_conversion(float inFarh)
{
　　　　float outCel;

　　　　outCel = (inFarh - 32.f) * 5.f / 9.f;

　　　　return outCel;
}

目が通しやすくなったんじゃないですか？

② コメントを書く時に、処理自体についてよりも、処理の理由を書くこと。つまり、
「ナニが起こっている」より「ナゼこうになっている」ということです。まずは
NG例から説明します。

bool IsValidNumber(unsigned int num)
{
　　　　if (num % 2 == 0)
　　　　　　　　return true;　　　// number okay
　　　　else
　　　　　　　　return false;　　　// number is NG.
}

これを見ると、分からない事が多すぎると思います。

なぜ % 2 はokay？

なぜ 2?

ルール２）を考えながら、書き直しましょうか。

bool IsValidNumber(unsigned int num)
{
　　　　if (num % 2 == 0)　　　　　　//　もしnumは0か偶数であれば、
　　　　　　　　return true;　　　　//　「使ってもいいよ」と復帰。
　　　　else　　　　　　　　　　　　// もしnumは奇数であれば、
　　　　　　　　return false;　　　　// 「使ったらアカン！」と復帰。
}

コメントのおかげで、処理がもっと分かりやすくなったと思います。しかし、
もう少し改善出来る箇所があると思います。


③ 関数の説明を書くこと。さっきの例を書き直すとこうになります。

// IsValidNumber() 文字配列のインデックス範囲チェック。
//　　　　引数： int num
//　　　　文字配列のインデックス値。0か偶数だけが有効です。
//
//　　　　復帰: bool
//　　　　numの値は範囲内だったら、trueを復帰。範囲外の場合では、falseを復帰
bool IsValidNumber(int num)
{
　　　　if (num % 2 == 0)　　　　　　//　もしnumは0か偶数であれば、
　　　　　　　　return true;　　　　//　「使ってもいいよ」と復帰。
　　　　else　　　　　　　　　　　　// もしnumは奇数であれば、
　　　　　　　　return false;　　　　// 「使ったらアカン！」と復帰。
}

長くなりましたが、関数自体が長くなればなるほど、コメントが大事になると
思います。

それでは、コメントを元気に書いていきましょう。５年後、１０年後、２５年後、
未来のプログラマー達が自分のソースを見ると、「コメントを書いてくれて、
ありがとう！」と思わせるように頑張りましょう。