« アルデンテの硬さが分らない | トップページ | 若さゆえの構想と妄想と暴走(その⑤) »

2012年6月12日 (火)ノー・コメント

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

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

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

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

float tc(float in)
{
    float out;

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

    return out;
}


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

セミコロン?

いいえ。

型変換キャスト?

いいえ、違います。

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

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

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

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

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?

ルール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;    // 「使ったらアカン!」と復帰。
}


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

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

follow us in feedly
result = encodeURIComponent( "http://www.accessgames-blog.com/blog/2012/06/post-75cb.html" );document.write( "result = " , result );&media=https%3A%2F%2Ffarm8.staticflickr.com%2F7027%2F6851755809_df5b2051c9_z.jpg&description=Next%20stop%3A%20Pinterest">

| | コメント (0) | トラックバック (0)

« アルデンテの硬さが分らない | トップページ | 若さゆえの構想と妄想と暴走(その⑤) »

プログラマー」カテゴリの記事

コメント

コメントを書く



(ウェブ上には掲載しません)


コメントは記事投稿者が公開するまで表示されません。



トラックバック


この記事へのトラックバック一覧です: ノー・コメント:

« アルデンテの硬さが分らない | トップページ | 若さゆえの構想と妄想と暴走(その⑤) »