コメントで意図を残す
コメントで意図を残す とは
//と/* */を使って、未来の自分が読めるコードを書こう。本レッスンでは、コメントで意図を残す の基本から実際の使いどころまでを整理し、現場で迷わず使える形に落とし込みます。
コードに「説明」をつける
プログラミングを 1 ヶ月続けると、必ず一度はこんな経験をします。「2 週間前に書いた自分のコード、なんでこう書いたのか思い出せない…」。コードは書いた瞬間がピークで、放置するとどんどん「他人のコード」になっていきます。これを防ぐのが コメント です。
コメントとは、JavaScript のエンジンには無視されるけれど、人間には読めるテキストのことです。JavaScript には 2 種類のコメントがあります。
JavaScript
// この行はコメント。// から行末までが無視される
/* この書き方は
複数行コメント。
/ と * で挟むあいだはぜんぶ無視される */上が 行コメント (//)、下が ブロックコメント (/* ... */) です。どちらもエンジンには影響を与えないので、自由にメモを残せます。
コメントを書く一番大事な理由は「未来の自分のため」です。半年後の自分は完全に他人。「なぜこう書いたか」を残しておくと、自分自身にとっての最高のドキュメントになります。
コメントを書く 3 つのタイミング
コメントはどこにでも書けますが、特に効くタイミングが 3 つあります。
JavaScript
// 1. 関数の役割を説明する
// ユーザーの BMI を計算する
function bmi(weight, height) {
return weight / (height * height);
}
// 2. なぜそうしたのか、を残す
const MAX_RETRY = 3; // 4 回以上は API が拒否するため
// 3. 一時的にコードを無効化する
// console.log("debug", data); // 本番リリース前にコメントアウト1 つめは関数の役割、2 つめは「なぜ?」、3 つめは一時的な無効化です。特に 2 つめが重要で、「ここで 3 を指定した深い事情」をコメントで残しておかないと、半年後の自分が「いや、10 でいいだろ」と書き換えてバグを生みます。
良いコメントは「何をしているか」ではなく「なぜそうしているか」を書きます。
x = x + 1の上に// x に 1 を足すと書くのは無意味。// 0-index から 1-index に変換するためと書けば価値があります。
コメントアウトとデバッグ
コードを「一時的に動かなくする」ことを コメントアウト と呼びます。これはデバッグの王道テクニックです。
JavaScript
function calc(a, b) {
// const result = a * b; // 旧仕様、念のため残す
const result = a + b; // 新仕様: 足し算に変更
return result;
}コメントアウトしておけば、/ を 2 つ消すだけで元に戻せます。ただし「コメントアウトしっぱなしの古いコード」が増えるとファイルが読みづらくなるので、git などのバージョン管理に慣れてきたら、コメントアウトせずにいったん削除する方針も検討してみましょう。
コードが評価される流れを図で見る
コメントは JavaScript エンジンが「無視する」と書きましたが、内部では次のような流れで処理されます。
エンジンは最初の 字句解析 という段階でコメントをまるごと捨てるので、コメントの中身がどれだけ長くても、実行時の性能には影響しません。安心してコメントを書きましょう。
よくある間違い
コメント周りでつまずきやすい落とし穴を 3 つ紹介します。
/*を閉じ忘れる — ブロックコメントは*/で閉じる必要があります。閉じ忘れると、その後のコード全部がコメントとして無視されて「実行されない」謎の状態になります- シャープ
#を使う —PythonやRubyでは#がコメントですが、JavaScriptでは違います。#を使うとSyntaxErrorです - コメントだけ書いて満足する —
// TODO: あとで直すのようなコメントを放置すると、永遠にあとでが来ません。TODOを書いたら期日や担当を一緒に書く、というルールにすると効果的です
もうひとつの落とし穴が「コメントとコードがズレる」問題です。コードを修正したのにコメントを直し忘れると、コメントが嘘をついている状態になります。コードを直したらコメントも直す、を習慣にしましょう。
JSDoc という拡張記法
ブロックコメントの /* を 2 つ星 /** にすると、JSDoc という特別なコメントになります。エディタが自動補完を効かせてくれる、ドキュメント生成ツールが拾ってくれる、といった恩恵があります。
JavaScript
/**
* 2 つの数値を足す
* @param {number} a 1 つめの数
* @param {number} b 2 つめの数
* @returns {number} a と b の合計
*/
function add(a, b) {
return a + b;
}最初のうちは普通のコメントで十分ですが、チームで開発するようになったらぜひ覚えておきたい記法です。
やってみよう
それでは課題に挑戦しましょう。関数 addWithNote を作って、次の手順で組み立ててください。
- 引数
aとbを受け取る - 関数の中に「2 つの数を足す」というコメントを 1 行入れる
a + bの結果をreturnする
テスト自体は戻り値しか見ないので、コメントの中身は自由です。ただし「ちゃんとコメントを書く習慣」を体で覚えるために、最低 1 行はコメントを入れて submit してみてください。
余裕があれば、ブロックコメント
/* ... */でもう 1 行説明を追加してみましょう。エディタの色が変わって、コメントとコードの区別が体感できます。
慣れてきたら、自分の他のコードにもコメントを足してみましょう。「3 ヶ月後の自分が見返したときに、迷わず読めるか?」を判断基準にすると、ちょうど良い分量が見えてきます。
よくある質問
Q. ブラウザと Node.js で動作は変わりますか？
A. JavaScript の構文・組み込み機能（配列・文字列・Promise 等）はどちらでも同じです。違いは DOM API（ブラウザ専用）と fs などのファイル系（Node 専用）など、実行環境固有の機能です。コアロジックは両方で動くため、テストもしやすくなります。
Q. ES6 以降の新機能は使っても大丈夫ですか？
A. 現代のブラウザ・Node.js は ES2020 以降の機能をほぼサポートしています。古い IE 等を対象にする必要が無ければ、let/const、アロー関数、分割代入、async/await を積極的に使ってください。トランスパイル（Babel/Vite）が必要なケースは年々減っています。
Q. TypeScript に進む価値はありますか？
A. 型情報があるとリファクタやエディタ補完が劇的に効くため、規模が大きくなるなら TypeScript への移行を強くおすすめします。最初は any を許容しつつ徐々に型を付ければ、JS の知識をそのまま活かせます。
次のレッスン
次は strict mode を意識する で、// と /* */ を使って、未来の自分が読めるコードを書こう を学びます。
事前確認 — 進む前に次の 3 つができることを確認しましょう。
- コメント の要点を自分の言葉で説明できる
- このレッスンの最小コード (または操作手順) を見ずに書ける
- 練習問題やクイズで間違えた箇所を読み直して理解した
理解度チェック (30 秒)
Q. コメント とは何か、1 文で説明してください。
A. 本文の「このレッスンで分かること」または冒頭の説明文を見直し、自分の言葉で要約できれば OK。詰まったら本レッスンの最初の H2 セクションを読み返してみましょう。
関連レッスン
要件
- 関数名は
addWithNote、引数はaとbの 2 つ - 戻り値は
a + bの合計 - 関数の中に 1 行以上のコメント (
//または/* */) を入れること
入出力例
test-cases.txt
addWithNote(1, 2) → 3
addWithNote(10, 20) → 30
addWithNote(-5, 8) → 3
addWithNote(0, 0) → 0