JavaScriptのコメントはこう書くべし! 活用法まで徹底解説

こんにちは!フリーランスの桃太郎です。

みなさん、プログラム内にコメントって入れてますか? 開発を進めていく上で、プログラムの中にコメントを入れることはとても大切なことです。

しかし初心者の方は処理を書くことに一生懸命なので、ついついコメントを入れ忘れてしまったりしますよね。そもそも書き方がわからない方もいるかもしれません。

そこで、この記事ではコメントについて徹底解説!

書き方のルールから、どのようなコメントを残すべきなのかまでバッチリご紹介していきます。

コメントはただプログラムの解説を残しておくだけでなく、もう一つ便利な使い方があります。それも併せて紹介していくので、ぜひ覚えていってください!

「コメント」とは?

それでは、まず最初に「コメント」についての基本的な知識から学習を進めていきましょう!

「コメント」は、JavaScriptプログラムとして実行されない文であり、一般的にコードの説明などを記述しておくメモのような位置づけです。

そのため、コードにどのような意味があるのかを第三者が素早く理解するための「道しるべ」にもなるわけです。

例えば、次の関数を見てください!

function abc( str, num ) {
    return str + num;
}

ちょっと極端な例ですが、いきなりこの関数を見ても何のために処理を行っているのかよく分かりませんよね?

関数の目的や引数の「str / num」が一体どんな値なのか…など、不明な点が多くあります。このようなコードに対して、「コメント」をコード内に記述しておけば誰でも理解しやすいわけですね。

特に、チーム開発などで不特定多数の人とコードをシェアする場合には必須とも言える機能です。本記事では、「コメント」の使い方について基本から応用技まで詳しく解説していきますのでぜひ参考にしてみてください!

コメントの使い方

1行のコメントの書き方

基本的な構文は以下の通りです。

// コメント文

スラッシュを2回続けて、その後にコメント文を書きます。

具体的なサンプルで書き方を確認して見ましょう。

// numの階乗を求める関数
function factorial(num){
    if( num<=1 ) return num; //1以下の場合は、そのまま値を出力
    return num*factorial(num-1);
}

//1から10までの階乗を求めてコンソールに出力
for(var i=1; i<11; i++){
    console.log(i + "の階乗 = " + factorial(i));
}

実行結果

1の階乗 = 1
2の階乗 = 2
3の階乗 = 6
4の階乗 = 24
5の階乗 = 120
6の階乗 = 720
7の階乗 = 5040
8の階乗 = 40320
9の階乗 = 362880
10の階乗 = 3628800

サンプルにある通り、1行コメントは行の先頭だけではなく、行の途中(//1以下の場合は、・・・)に書くことも可能です。

複数行のコメントの書き方

では次に、複数行にわたってコメントを書く方法を解説します。

まず基本的な構文は以下の通りです。

/*
コメント
コメント
コメント
*/

/* 〜 */で囲むことで複数行にわたる内容をコメントにすることが可能です。

こちらも具体的なサンプルで使用方法を確認しましょう。

/*
関数概要:階乗を出力する処理
引数:num 数値
戻り値:numの階乗値
*/
function factorial(num){
    if( num<=1 ) return num; //1以下の場合は、そのまま値を出力
    return num*factorial(num-1);
}

//1から10までの階乗を求めてコンソールに出力
for(var i=1; i<11; i++){
    console.log(i + "の階乗 = " + factorial(i));
}

*実行結果は先ほどのサンプルと同一なので省略します。

HTML/CSSのコメントとの違い

これまで、JavaScriptにおける「コメント」について見てきました。そこで、よく一緒に使う言語の「HTML / CSS」におけるコメントもここでまとめて確認しておきましょう!

まず、HTMLにおける「コメント」は以下のとおりです。

<!— 1行のコメントになります -->

<!--
複数行の
コメント
になります
-->

<!–– ––>で囲むことでその中に記述された文字列はすべてコメント扱いになります。

CSSの場合は以下のとおり!

/* 1行のコメントになります */

/*
複数行の
コメント
になります
*/

/* */で囲むことですべての文字列がコメント扱いになります。

JavaScriptを複数行コメントする場合とCSSのコメントは同じ記述方法なので、混乱しないように注意しておきましょう!

コメントアウトをする理由

ここからは、コメントを活用する事例をご紹介します!

例えば、プログラムを作成していざ実行すると意図したとおりに動かなかったりするケースがあります。

不具合の原因がどこにあるのか解らない場合に、怪しいコードを「コメント」扱いにして原因を究明(デバッグ)するという手法があります。このようなコメントのことを「コメントアウト」と呼んだりしますが、このようにすることで正常に実行されるかどうかをチェックするわけです。

つまり、エラーが出なくなり正常に実行できた場合は、コメント扱いにした部分に原因があると断定できるわけです!

コメントによるデバッグ方法

それでは、実際にコメントアウトを行ってみましょう!

次のサンプル例を見てください。

var array = ['バナナ', 'リンゴ', 'イチゴ', 'メロン'];

something(array);

function something( array ) {
    array.forEach( function( value ) {

        console.log( array );

    })
}

この例では、配列を用意してその中身だけをコンソールログに出力するというシンプルな関数を記述しています。

しかし、このままでは正しく配列の中身を取り出すことができません。意図したとおりに動かないわけですが、構文エラーも出ない状態なので原因究明に時間が掛かりそうです。

このような時に「コメントアウト」をしながら原因を探っていくわけです!

まず最初に、関数が配列をちゃんと受け取っているのかを疑ってみましょう。そこで、関数の中身をすべてコメントアウトしてから引数だけをコンソールログに出力してみます。

function something( array ) {
    console.log( array );

/*
    array.forEach( function( value ) {
        console.log( array );
    })
*/

}

実行結果

["バナナ", "リンゴ", "イチゴ", "メロン"]

このようにコメントアウトすることで、とりあえず関数が正しく動いているのかだけをチェックすることが出来るわけです。

実行結果を見ると、しっかりと配列データを受け取ることが出来ているのが確認できますね。

次に、「forEach()」を使って配列の中身を取り出していますが、このコールバック関数の引数を調べてみましょう!

function something( array ) {
    array.forEach( function( value ) {
        console.log( value );
        
        // console.log( array );
    })
}

実行結果

バナナ
リンゴ
イチゴ
メロン

「forEach()」の中身をコメントアウトし、新しくconsole.log()を使ってチェックしています。すると、実行結果には正しく配列の中身だけが出力されましたね!

そこでコードをよーく見ると、最初にforEach()の中に記述していたのが「console.log( array )」と間違っているのが分かります。「array」ではなく「value」と記述しなければいけませんね。

このサンプル例は非常にシンプルなコードですが、実際のコードは数十行にわたり記述されている関数も多いのでコメントアウトは有効な手段となります。

このような原因究明の方法(デバッグ)は必ず役に立つテクニックなので、ぜひみなさんも覚えておくようにしましょう!

コメントには何を書くべきか

これまでコメントの書き方を解説してきましたが、コメントの中身の書き方、つまりどのような内容のコメントを書くべきなのかについて解説します。

コメントの内容一つでそのプログラマーが初心者なのか中上級者なのかは一目でわかるものです。ここではコメントのコツについて3つご紹介します。

わかりきったコメントは書かない

ソースを見れば処理の内容がわかるものについてわざわざコメントをつける必要はありません。

以下は良くない例です。

function add(n,k){
    //nとkを足す
    return n + k;
}

//nとkを足した数をコンソールにだす
console.log(add(2,3));

必要な背景や理由を書く

例えば、要件や仕様により処理の制約がある場合などは、開発者本人は判っていて実装していても、あとで他の人が見返した時に、なぜそのような処理にしたのか解らないことがあります。

そのような時は処理の制約がある理由をコメントに残すことが大事です。

// 要件◯◯により画面へ表示する数は最大10とする制約あり
const DISPLAY_CNT = 10;

for(var i=1; i<DISPLAY_CNT; i++){
    (中略)

JSDocコメントも活用してみる

コメントは誰でも自由に記述ができる反面、人によって書き方がバラバラになってしまうので読みづらいケースも出てきます。そこで、ある程度のルールに沿ってコメントを書くことで可読性を高めることができます。

一般的によく使われているコメントのフォーマットが「JSDocコメント」になります。記述方法としては、「/**」で始まり「*/」で終わるコメントになっており、その中身を一定のルールに沿って記述していきます。

次のサンプル例を見てください!

/**
*ユーザーの情報を管理するオブジェクト
*@constructor
*@param {String} name ユーザー名
*@param {Number} age ユーザーの年齢
*/
function UserInfo(name, age) {
    /**
    *ユーザーの名前
    *@type {String}
    */
    this.name = name;
    
    /*
    *ユーザーの年齢
    *@type {Number}
    */
    this.age = age;
    
    /*
    *ユーザーの名前を取得します
    *@return {String} ユーザー名
    */
    this.getName = function() {
        return this.name;
    }
}

「@param」「@type」などのキーワードを使い、受け取る引数や変数の型・意味などを記述していくわけです。共通のフォーマットを利用することでコードの可読性は非常に高くなるので、ぜひ参考にしてみてください!

まとめ

本記事ではコメントの基本的な書き方から、コメントアウト、そしてそのコメントにどのような内容を書くべきかについてご紹介しました。

コメントは初心者からすると軽視しがちなところがありますが、中上級プログラマーになればなるほどコメントにはとても気を使い有益なコメント内容を残すものです。

あなたもぜひ脱初心者を目指して、良いコメントを書けるように日々気をつけてみてください。もし、今後コメントに関して迷うことがあれば、ぜひこの記事を思い出して下さいね。

LINEで送る
Pocket

「プログラミング、右も左もわからない…」という方にオススメ

当プログラミングスクール「侍エンジニア塾」では、これまで6000人以上のエンジニアを輩出してきました。

その経験を通してプログラミング学習に成功する人は、「目的目標が明確でそれに合わせた学習プランがあること」「常に相談できる人がそばにいること」「自己解決能力が身につくこと」この3つが根付いている傾向を発見しました。

侍エンジニア塾は上記3つの成功ポイントを満たすようなサービス設計に磨きをかけております。

cta_under_bnr

「自分のスタイルや目的に合わせて学習を進めたいな」とお考えの方は、ぜひチェックしてみてください。

書いた人

侍テック編集部

侍テック編集部