コメントとコードの整え方

コードは書く時間より読む時間のほうが長くなります。読む相手はたいてい3か月後の自分です。そのときの自分に向けて、少しだけ親切にしておく方法がコメントと整形です。

2種類のコメント

#include <stdio.h>

int main(void) {
    // 1行コメント。ここから行末までは無視される
    int tanka = 250;   // 行の途中からでも書ける

    /* 複数行のコメント。
       ここも全部が無視されます。
       長い説明はこちらが向いています。 */
    printf("単価 %d 円\n", tanka);
    return 0;
}

コメントはコンパイルの前に取り除かれるので、実行速度には一切影響しません。安心して書けます。

コメントに書くのは「なぜ」

    tanka = tanka * 110 / 100;   // 悪い例: 単価に110を掛けて100で割る
    tanka = tanka * 110 / 100;   // 良い例: 消費税10%を上乗せ（切り捨て）

コードを読めば「何をしているか」は分かります。分からないのは「なぜそうしたか」です。仕様の根拠、選んだ理由、あえて避けたこと。そこを書くとコメントの価値が跳ね上がります。

整え方の基本4つ

・インデント … { の中は半角スペース4つ（またはタブ）で1段下げる。これだけで構造が目で見えます。
・1行1文 … ; で区切って何文も並べない。
・空行でまとまりを作る … 入力・計算・出力のかたまりを空行で分けます。
・名前で語る … int a; より int tanka;。良い名前はコメント1行分の説明を省いてくれます。

#include <stdio.h>

int main(void) {
    // 入力
    int kosuu;
    printf("個数: ");
    scanf("%d", &kosuu);

    // 計算（単価250円・税10%）
    int zeinuki = 250 * kosuu;
    int zeikomi = zeinuki * 110 / 100;

    // 出力
    printf("税込 %d 円\n", zeikomi);
    return 0;
}

中身は難しくありませんが、3か月後の自分がすぐ読めます。

罠・注意

/* */ は入れ子にできない。 /* から最初の */ までがコメントです。コメントの中に別の /* */ があると、途中で終わってしまい、残りがコードとして解釈されて謎のエラーになります。広い範囲を一時的に消したいときは // を各行に付けるのが安全です。

コメントアウトの消し忘れ。 動かなくなったコードを // で隠したまま放置すると、後で「これは生きているのか」が分からなくなります。不要になったら消します。

コードとコメントの食い違い。 コードだけ直してコメントを直さないと、嘘の説明が残ります。嘘のコメントは、無いより有害です。

まとめ

// は行末まで、/* */ は範囲指定。コメントはコンパイル時に消えるので速度に影響しません。書くべきは「何を」ではなく「なぜ」。インデント・1行1文・空行・良い名前の4つで、コードの読みやすさは十分に整います。