プログラムのコメントの書き方をお伝えします【初心者向け】

プログラミングをしたい方

プログラムのコメントを書く意味がわからないな～。プログラムコメントを書く際に気をつけることってあるの？良いコメントの例も知れると嬉しいな。

そんな疑問に答えます！

プログラムのコメントの書き方をお伝えします

プログラミングコメントの目的は次の2つです。

プログラムの理解を助けるためという目的はさらに2つに分けられます。

初学者の方はまず、自分のためにコメントを書くようにしましょう。 慣れてきたら読む人も意識したコメントが書けるようになればOKです。

最初は大規模なコードを書くこともないと思うのと、プログラミング上達のためには最初に処理全体の流れを理解することが大切です～。

プログラムのコメントのポイント

プログラミングコメントは処理の流れを理解するために書きましょう。 最初は自分でコメントで処理を書き出すことで、処理全体の流れを理解することができます。

その際、プログラムのブロック構造を意識してコメントを書くと良いと思います。

// 1から100までを繰り返す処理
    // 3で余りが0の場合かつ5で余りが0の場合はfuzzbuzzと表示
    // 3で余りが0の場合はfuzzと表示
    // 5で余りが0の場合はbuzzと表示
    // 上記以外は数値をそのまま表示

次に書いた１行ずつのコメントに対して処理を書いていきます。 最初にコメントで処理の流れを確認したので、その処理を１つづつ埋めていくイメージです。

// 1から100までを繰り返す処理
for (let i = 1; i < 100; i++) {

    // 3で余りが0の場合かつ5で余りが0の場合はfuzzbuzzと表示
    if ((i % 3 === 0) && (i % 5 === 0)) {
        console.log("fuzzbuzz");
    // 3で余りが0の場合はfuzzと表示
    } else if (i % 3 === 0) {
        console.log("fuzz");
    // 5で余りが0の場合はbuzzと表示
    } else if (i % 5 === 0) {
        console.log("buzz");
    // 上記以外は数値をそのまま表示
    } else {
        console.log(i);
    }

}

良いプログラムコメントの例

ここまで初学者の方向けにコメントの書き方をお伝えしましたが、更に上達したい方向けに良いコメントの例についてもお伝えしたいと思います。

なぜそうしたのか理由を書いているコメント

コメントはプログラムの補足情報のため、プログラムの理由が書かれていると読んだときにわかりやすいです。

// パフォーマンス改善のためバッファを利用
let string = buf.toString('utf-8', 0, buf.length);

分かりづらい処理の説明などの場合もあると良いですね。

// 三角形の面積を計算（底辺×高さ÷2）
let triangleArea = bottom * height / 2;

ソースコードの要約

複数のコードをまとめて処理内容を説明するのも可読性が高くなります。

// トランザクション
connect.beginTransaction(function(err) {
    ・・・
});

プログラミングを学ぶのにオススメの本

より良いプログラミングにはリーダブルコードがオススメです！今回紹介したコメントだけではなく、変数の命名のルールなどについて解説しています。私は3回くらい繰り返し読んでいますよ〜。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

Amazon

楽天

まとめ

今回、より良いプログラミングコメントの書き方についてお伝えしました。ちょっとずつ意識することでスキルとして見についていくと思います。少しでも参考になったのであれば嬉しいです。