コメントで意図を残す
このレッスンで分かること
//は行末まで、/* */は囲んだ範囲が、実行されないメモになります- コメントには「何をしているか」ではなく「なぜそうしたか」を書きます
3 ヶ月後の自分は他人
自分で書いたコードでも、3 ヶ月経つと「なぜこう書いたのか」は思い出せません。そこで、JavaScript が読み飛ばす場所をコードの中に作れるようになっています。それがコメントです。プログラムの動きには一切影響しません。人間だけが読むメモです。
JavaScript
// 閲覧数は運営から日次でしか届かないため、当日分は 0 のまま出す
console.log(3 * 120);1 行目は // で始まっているので、JavaScript から見れば存在しないのと同じです。それでも、このファイルを初めて開いた人は、1 行目を読むだけで事情が分かります。
メモが 1 行で終わらないとき
コメントには 2 種類の書き方があります。
JavaScript
// これは行コメント。この行の終わりまでがコメント
/*
これはブロックコメント。
複数行をまとめてコメントにできる。
*/| 記法 | 範囲 | 主な使いどころ |
|---|---|---|
// | 書いた位置から行末まで | 1 行のメモ、コードの右側への補足 |
/* */ | /* から */ まで | 数行の説明、書きかけのコードの一時停止 |
行コメントは、コードの右側に書くこともできます。
JavaScript
console.log(3 * 120); // 作品 3 件、それぞれ 120 回の閲覧長い説明を右側に書くと横に伸びて読みにくくなるので、2 行以上になりそうなら、説明したいコードの真上へ移します。インデント (行頭の空白) は説明する対象とそろえます。ずれていると、どこにかかる説明なのかが読み取れません。
VS Code では、行を選んで
Ctrl+/(Mac はCommand+/) を押すと、選んだ範囲がまとめてコメントになります。もう一度押すと戻ります。
コードを読めば分かることは書かない
コメントは書くほど良いというものではありません。中身のないコメントはノイズになります。
JavaScript
// 3 と 120 をかける
console.log(3 * 120);これはコードを読めば分かることを繰り返しているだけです。しかも、あとで値を変えたときにコメントだけ古いまま残り、読む人を混乱させます。嘘をつくコメントは、無いより有害です。
役に立つのは、コードからは読み取れない情報です。なぜその方法を選んだか、一見おかしく見える処理の背景、これから直す予定、注意してほしい落とし穴。この 4 つを思い出してください。
TODO と FIXME は世界共通のしるしです。TODO はあとでやること、FIXME は壊れていて直すべきところを表します。多くのエディタがこの 2 語を色付きで目立たせ、一覧にもしてくれます。
よくある間違い
- 文字列の中の
//をコメントだと思う — 文字列の内側はコメントになりません。"https://example.com/profile"の//も、ただの 2 文字として残ります - ブロックコメントを入れ子にする —
/* */は入れ子にできません。内側の*/で閉じてしまい、残りが構文エラーになります。まとめて外したいときは行コメントを重ねます
要件
- 関数名は
buildCommentNote、引数はtitleとnoteの 2 つ (どちらも文字列) - 戻り値は
//+ title + 改行 +/*+ note +*/をつないだ文字列 //と/*のあと、*/の前にはそれぞれ半角スペースを 1 つ入れること- 改行は
\nを使うこと
入出力例
buildCommentNote("profile", "自己紹介を組み立てる") → "// profile
/* 自己紹介を組み立てる */"
buildCommentNote("setup", "TODO 第 8 章で置き換える") → "// setup
/* TODO 第 8 章で置き換える */"
buildCommentNote("setup", "") → "// setup
/* */"
buildCommentNote("", "") → "//
/* */"ヒント
