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

あなたが学ぶべき言語はJavaScriptで大丈夫?

画像:Shutterstock

ここまで、JavaScriptのコメントについてご紹介しましたが、

JavaScriptの学習大変だな。難しいな
覚えることが多すぎてよくわからない!

なかにはこのように感じた方もいらっしゃるのではないでしょうか。そのような不安を少しでも抱いたのならば、一度原点に立ち返って「本当にJavascriptを学ぶべきなのか」いまいちど考えてみましょう。

JavaScriptを学ぶ目的は明確ですか?

あなたがJavaScriptを明確にやりたいことが決まっているうえで学習しているなら何も問題はありません。このまま学習を続けていきましょう。

しかし、もしあなたの学習目的が、

JavaScriptは初心者向けって聞いたから。
応用力があって何にでも使えそうな言語だから。

といったような理由であるならば、いまいちどあなたがプログラミングを学ぶ目的から見直したほうがいいかもしれません。このような漠然とした目的で学習を続けると、分からないことにぶつかった時、モチベーションを維持できず挫折してしまう可能性が非常に高くなってしまいます。

特にプログラミングは挫折率が高く習得が難しいスキルと言われています。一節によると、プログラミングを独学で学習する人の90%以上が挫折してしまうという話もあるほどです。

もし、あなたが「作りたいものはあるけど、何が必要かわからないし特に学習プランも決めていない」といった状況であるならば、一度こちらの”プログラミング学習プラン診断アプリ”をご利用ください。

簡単な質問からあなたに必要なスキルや簡易的な学習プランを提示いたします。

挫折せず確実にJavaScriptを習得したいなら

あなたにJavaScriptを学習する目的が明確にあり、なおかつ独学での学習に不安を感じているならば、プログラミングスクールの受講をおすすめいたします。

いきなりプログラミングスクールはちょっと……。

と感じるかもしれません。プログラミングスクールはたしかに高額ではありますが、PHPやCakePHPを習得することが出来れば、簡単に元を取ることができます。

大手クラウドソーシング「クラウドワークス」の案件を見てみると、JavaScriptを使った案件は平均30〜50万円ほどが一般的です。つまりJavaScriptを習得して、1〜2件の案件をこなせば、元は取れるということですね。

でも本当にプログラミングを習得できるの?

たしかに、プログラミングスクールに通っても思うような結果を得られない方もなかにはいらっしゃいます。その多くがスクール選定の時点で間違っていることがほとんどです。

弊社侍エンジニア塾では、あなたの目的に合わせて現役エンジニア講師が、オーダーメイドでカリキュラムを作成いたします。そのため、固定のカリキュラムで起こりうる弊害などの一切を省き、必要なスキルだけを最短距離で習得することができます。

まずは一度、弊社の無料体験レッスンをご利用ください。専属コンサルタントがあなたのプログラミング学習に対する不安やキャリアの悩みなどさまざまな質問にお答えいたします。

無料体験レッスンを予約する

まとめ

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

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

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

LINEで送る
Pocket

SEからWebエンジニアへ転職した理由

侍エンジニア塾卒業生の小池さんは、以前は社内SEとして約5年ほど勤務していました。しかし業務内容は社内のヘルプデスク対応など、プログラムを書く仕事は全くなかったそうです。

SEながらプログラムを書けない現状に「将来仕事がなくなるんじゃないか」と不安を感じ、プログラミング学習を決意。

弊社スクールで学習し、無事ベンチャー企業のプログラマーとして転職に成功しました。そんな小池さんの学習法や転職体験談を伺いましたので、是非ご覧ください。

「プログラミングができないSEは仕事がなくなる」不安を感じたSEが未経験から転職成功するまで
更新日 : 2019年10月7日

書いた人

湯浅 桃太郎

湯浅 桃太郎

20代は役者、30代はエンジニア、そして40代を迎えた現在、Webライターとして活動しながら、3人の息子たちの家庭教育、アンチエイジングなどにも力を入れて日々ノマドライフを楽しんでいます。

おすすめコンテンツ

あなたにぴったりなプログラミング学習プランを無料で診断!

プログラミング学習の効率を劇的に上げる学習メソッドを解説