【STEP.03】
JavaScriptのコメントの書き方をマスターしよう!

コメントとは

コメントとは、名前の通り、スクリプトの動作には関係しないメモ的な情報のことです。

自分が記述したコードであっても、時間が経ってしまうと、何が書いてあったのか覚えていないということはよくあります。

ましてや、他人が書いたコードを読み解くのは、多くの場合、とても大変なことです。

しかし、コードの要所要所にコメントを残しておくことで、そのコードが何をしているのか、何を目的とした記述なのかなど、概要を把握しやすくなります。

特に、長期的なメンテナンスを前提としたアプリでは、コメントの記述は必須です。

コメントの書き方

コメントには、単一行コメント複数行コメントの2種類があります。

まずは、単一行コメントの書き方から見ていきましょう。

単一行コメント

単一行コメントは次のように記述します。

// コメント

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

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

// 四角形の面積を求める関数
function getSquareArea (width=1, height=1) { // 既定値はそれぞれ1
  return width * height;
}

// 四角形の面積をコンソール画面に出力
console.log(getSquareArea(2,3));

// 結果:6

サンプルにある通り、単一行コメントは行の先頭だけではなく、行の途中に記述することも可能です。

複数行コメント

複数行コメントは次のように記述します。

/*複数行
コメント*/

/* 〜 */」で囲まれたブロックがコメントとみなされます。

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

/*
関数概要:四角形の面積を求める関数
引数:width 横の長さ
引数:height 縦の長さ
戻り値:四角形の面積
*/
function getSquareArea (width = 1, height = 1) { // 既定値はそれぞれ1
  return width * height;
}

// 四角形の面積をコンソール画面に出力
console.log(getSquareArea(2,3));
	
// 結果:6

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

JavaScriptと一緒に使用されることの多いHTML / CSSのコメントの書き方を確認しましょう。

まず、HTMLにおけるコメントは次のように記述します。

<!--単一行コメント-->

<!--複数行
コメント-->

CSSにおけるコメントは次のように記述します。

/*単一行コメント*/
     
/*複数行
コメント*/

CSSでは「/* ~ */」で囲まれたブロックがコメントと見なされます。

JavaScriptの複数行コメントとCSSのコメントは同じ記述方法なので、混乱しないように注意する必要があります。

単一行コメント「//」、複数行コメント「/*~*/」いずれを優先して使うべきか?

//」と「/*~*/」、いずれを優先して利用すべきでしょうか。

// 単一行コメント

/*複数行
コメント*/

結論から言うと、原則として単一行コメント「//」を優先して利用すべきです。

なぜなら、「/*~*/」は入れ子にできません。

そのため、「/*~*/」を含んでいるコードをさらに「/*~*/」でコメントアウトした場合、構文エラーの原因となります。

また、「*/」は正規表現リテラルの中で発生する可能性もあります。

たとえば、以下のコードは典型的な構文エラーの例です。

/*let reg = /[0-9]*/」の範囲で複数行コメントが終了してしまうためです。

/*
let reg = /[0-9]*/.match(str);
*/

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

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

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

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

良くない例を見てみましょう。

function add (a,b) {
// aとbを足す
 return a + b;
}
     
// aとbを足した数をコンソール画面に出力
console.log(add(1,2));

必要な背景や理由を書く

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

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

// 要件○○により画面へ表示できる数は最大で10個までとなっています。
const DISPLAY_CNT = 10;
     
for (var i = 1; i < DISPLAY_CNT; i++) {
  ...中略...
}

コメントアウトとは

コメントは、特定の文を無効にする場合に利用することもあります。

たとえば、以下の文はコメントと見なされ、実行されません。

// window.alert('Hello、JavaScript!');

/*
window.alert('Hello、JavaScript!');	
*/

このように、文をコメント化(無効化)することをコメントアウトといいます。

デバッグなどに際しては有効な手法なので、覚えておくとよいでしょう。

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

次のサンプルコードをご覧ください。

let array = ['横浜流星', '北村匠海', '山﨑賢人', '岡田将生'];

output(array);

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

サンプルコードのoutput関数は、配列の中身を順番にコンソール画面に出力することを期待した関数です。

しかし、このままでは配列の中身を順番に取り出すことができません。

期待通りに動作もしませんが、構文エラーも出力されない状態です。

このような時にコメントアウトを活用しながら期待通りに動作しない原因を探っていきます。

まず最初に、関数が配列を正しく受け取っているのかを疑ってみます。

そこで、output関数の中身をコメントアウトしてから引数だけをコンソール画面に出力してみます。

let array = ['横浜流星', '北村匠海', '山﨑賢人', '岡田将生'];

output(array);

function output(array) {
  console.log(array);
		
/*
  array.forEach(function(value) {
    console.log(array);
  })
*/
}
// 結果:["横浜流星", "北村匠海", "山﨑賢人", "岡田将生"]

このようにコメントアウトすることで、とりあえず関数が正しく動作しているのかだけを確認することができます。

実行結果を見ると、正しく配列の中身を受け取れていることが確認できます。

次に、forEachメソッドを使って配列の中身を取り出していますが、このコールバック関数の引数を調べてみます。

let array = ['横浜流星', '北村匠海', '山﨑賢人', '岡田将生'];

output(array);

function output(array) {
  array.forEach(function(value) {
    console.log(value);
    //console.log(array);
  })
}
// 結果:横浜流星, 北村匠海, 山﨑賢人, 岡田将生

forEachメソッドの中身をコメントアウトし、新しくconsole.logメソッドを使って確認します。

すると、実行結果には正しく配列の中身だけが出力されました。

そこでコードをよく見てみると、最初にforEachメソッドの中に記述していた「console.log(array)」が間違っているのが分かります。

console.log(value)」ではなく「console.log(array)」と記述していたことで期待通りに動作しなかったことがわかりました。

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


コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です