HTML のコメントは「未来の自分と他人へのメモ」
まず前提から。
HTML のコメントは、
<!-- ここがコメント -->
という形で書きます。
ブラウザには表示されませんが、
ソースコードを開くと見える「メモ」です。
一番の役割は、
「未来の自分や、同じコードを読む人への説明」 です。
「なぜこう書いているのか」
「どこからどこまでが何のブロックなのか」
を短く残しておくことで、
あとから読み返したときの理解が圧倒的に楽になります。
コメントの基本構文と OK / NG パターン
コメントの書き方の基本形
HTML のコメントは、必ずこの形です。
<!-- ここにコメントを書く -->
<!-- で始まり、--> で終わります。
この間に書いたものは、ブラウザには表示されません。
例：
<!-- ここからヘッダー -->
<header>
<h1>My Site</h1>
</header>
<!-- ここまでヘッダー -->
NG：コメントの中に「–」を入れない
HTML のコメントの中に、--（ハイフン 2 つ）を入れるのは仕様上 NG です。
悪い例：
<!-- ここは NG -- コメント -->
ブラウザがうまく解釈できなかったり、
思わぬところでコメントが終わったと判断されることがあります。
どうしても「–」を書きたいときは、
スペースを入れるなどして避けます。
<!-- ここは OK - - コメント -->
どこにコメントを書くか：ブロックの「上」か「前後」
セクションの区切りにコメントを入れる
ページが大きくなってくると、
「ここからどこまでが何のエリアか」が分かりにくくなります。
そんなとき、
「ブロックの前後にコメントを入れる」 と読みやすくなります。
例：
<!-- ヒーローセクション（トップの大きな見出し部分） -->
<section class="hero">
<h1>ようこそ My Site へ</h1>
<p>ここでは Web 開発の基礎を学べます。</p>
</section>
<!-- /ヒーローセクション -->
「ここからヒーローセクション」
「ここまでヒーローセクション」
と書いておくと、
長いファイルでも構造が一目で分かります。
一行コメントで「意図」を残す
「なぜこのタグが必要なのか」
「なぜこのクラス名なのか」
といった“意図”を短く残すのも有効です。
<!-- スクロール時に JS で固定するためのヘッダー -->
<header class="site-header is-sticky">
<h1>My Site</h1>
</header>
コードだけ見ても分からない「理由」を、
一行コメントで補ってあげるイメージです。
HTML コメントと JavaScript / CSS のコメントの違い
HTML コメントは「HTML の中だけ」で有効
HTML のコメントは、
HTML の中でだけ有効です。
<!-- これは HTML のコメント -->
<p>こんにちは</p>
一方、JavaScript や CSS には
それぞれ専用のコメント記法があります。
JavaScript：
// これは JS の一行コメント
/* これは JS の複数行コメント */
CSS：
/* これは CSS のコメント */
HTML の中に <script> や <style> を書く場合、
その中では HTML のコメントではなく、
JS / CSS のコメント記法を使う 必要があります。
悪い例：
<style>
<!-- これは NG -->
body {
background: #fff;
}
</style>
正しい例：
<style>
/* これは OK */
body {
background: #fff;
}
</style>
コメントに「コード」を残しっぱなしにしない
一時的なコメントアウトと、永遠のゴミの違い
開発中によくやるのが、
「一旦このコードを無効にしたい」というときのコメントアウトです。
<!--
<nav>
<a href="/old-page">旧ページ</a>
</nav>
-->
これは一時的には便利ですが、
そのまま放置すると「何のために残っているのか分からないゴミ」になります。
大事なのは、
「後で戻すつもりのコード」なのか
「もう使わないけど怖くて消せないコード」なのか
を自分で意識することです。
後者の場合は、
バージョン管理（Git など）に任せて、HTML からは消す
という判断ができると、コードがきれいに保てます。
コメントは「説明」のために使う
「使わないコードの墓場」にしない
この感覚がとても大事です。
コメントに書くべきこと・書かなくていいこと
書くべきなのは「意図」と「境界」
コメントに向いているのは、主にこの 2 つです。
なぜそうしているのか（意図・理由）
どこからどこまでが何のブロックか（境界）
例：
<!-- スクリーンリーダー用に、見た目では非表示の見出し -->
<h2 class="visually-hidden">メインコンテンツ</h2>
コードだけだと
「なんで見えない見出しがあるの？」
となりますが、
コメントがあることで意図が伝わります。
逆に、
「見れば分かること」を長々とコメントするのは逆効果です。
悪い例：
<!-- これは h1 タグです -->
<h1>タイトル</h1>
これはコードを読めば分かるので、
コメントとしての価値はほぼありません。
初心者として「コメントの書き方」で掴んでほしいこと
HTML のコメントは、
<!-- こう書く -->
という形で書く、ブラウザに表示されないメモです。
ブロックの前後に置いて「ここからここまでが何か」を示す
「なぜそうしているのか」という意図を短く残す
JS / CSS の中では、それぞれのコメント記法を使う
一時的なコメントアウトを“永遠のゴミ”にしない
「見れば分かること」ではなく「見ただけでは分からない理由」を書く
あなたがコメントを書くときに、
「これは未来の自分や他人にとって、本当に役に立つ一文か？」
と一度だけ立ち止まれるようになったら、
もうコメントを“ノイズ”ではなく“ドキュメント”として扱えている状態です。
