CSS のコメント規約 - 何をどこに書くか
CSS のコメントはコードの意図を伝える手段ですが、書きすぎると可読性を下げ、書かなさすぎると後から読む人が困ります。何にコメントを付けて何に付けないか、その基準がチーム内で共有されていないと、コメントの量も質もばらつきます。
コメントが必要な場面と不要な場面
CSS は宣言的な言語なので、プロパティ名と値を見ればやっていることは分かります。color: red に「文字色を赤にする」というコメントを付けても情報量はゼロです。
コードを読めば分かること。display: flex に「フレックスにする」と書くのは冗長。
コードからは読み取れない「なぜそうしたか」という意図や、将来の読み手が疑問に思いそうな判断の根拠。
コメントを書くべきかどうかの判断基準は「このコードを初めて見た人が、なぜこう書いたのか疑問に思うかどうか」です。疑問が生まれないコードにはコメントは要りません。
「なぜ」を書く
CSS で最もコメントが必要なのは、一見すると不自然に見える記述です。
.modal {
/* iOS Safari でモーダル背景のスクロールを防ぐ */
-webkit-overflow-scrolling: touch;
}
.tooltip {
/* 親要素の overflow: hidden に切られないよう fixed で浮かせる */
position: fixed;
}-webkit-overflow-scrolling: touch だけ見ても、なぜこのプロパティが必要なのか分かりません。ブラウザ固有のバグ対応やハック的な記述には、対象ブラウザや発生条件をコメントで残しておかないと、後から誰かが「不要では？」と削除してしまう危険があります。
ブラウザのバグ回避や非直感的な解決策。対象ブラウザとバグの内容を記載する。
top: -3px のような調整値。なぜその数値なのか、何と揃えるための値なのかを書く。
セクション区切りのコメント
ファイルが長くなると、どこからどこまでがどのパーツのスタイルなのか分かりにくくなります。セクションの区切りにコメントを入れる方法はいくつかあります。
/* ==========================================================================
Header
========================================================================== */
.header { ... }
/* --------------------------------------------------------------------------
Navigation
-------------------------------------------------------------------------- */
.nav { ... }このスタイルは Normalize.css や Harry Roberts の CSS Guidelines で採用されている形式です。視覚的に目立つので、スクロールしたときにセクションの境目がすぐ分かります。
ただし、コンポーネント単位でファイルを分割しているプロジェクトでは、ファイル自体がセクションの区切りになるので、ファイル内にこの種のコメントを入れる必要性は薄れます。
1 ファイルに複数コンポーネントのスタイルが入っている場合。ファイル分割ができない環境やレガシーコードの保守。
header.css、nav.css のようにファイルが分割されている場合。ファイル名自体がセクション名になる。
TODO・FIXME・HACK
一時的な対応や将来の修正予定を示すコメントには、検索しやすいプレフィックスを付けます。
/* TODO: デザイン確定後にカラートークンに置き換える */
.badge {
background: #e74c3c;
}
/* FIXME: Chrome 120 で修正済み、次回リリースで削除可 */
.card {
transform: translateZ(0);
}
/* HACK: IE11 で flex-basis が効かない問題の回避 */
.column {
flex: 1 1 0%;
}将来やるべき作業。今は仮実装だが、後で正式な対応が必要な箇所。
既知の問題がある箇所。バグの原因が分かっているが、今は修正できない場合。
意図的な非正攻法。正しいやり方ではないが、特定の事情でこう書いている箇所。
これらのプレフィックスはエディタの検索やリンターで一括検出できるので、定期的に棚卸しして不要になったものを消す運用とセットで使います。放置するとコメント自体がノイズになります。
Sass/SCSS でのコメントの使い分け
Sass には /* */ と // の 2 種類のコメント構文があり、出力される CSS に残るかどうかが異なります。
/* この行はコンパイル後の CSS に残る */
.card {
// この行はコンパイル後の CSS には残らない
padding: 16px;
}| 構文 | 出力 CSS に残るか | 用途 |
|---|---|---|
| / / | 残る（圧縮時は消える） | ライセンス表記、公開コメント |
| // | 残らない | 開発者向けメモ、意図の説明 |
開発者向けの「なぜ」を書くコメントは // で十分です。コンパイル後の CSS にまで残す必要はありません。/* */ を使うのは、ライセンス表記やソースマップを使わない環境でデバッグの手がかりを残したい場合に限られます。
コメントを書かない努力
コメントが必要になるのは、コード自体が意図を伝えきれていないサインでもあります。
/* 悪い例: コメントで補足しないと意図が分からない */
.item {
/* カード間の余白を 16px にする */
margin-bottom: 16px;
}
/* 良い例: 変数名が意図を伝えている */
.item {
margin-bottom: var(--spacing-card-gap);
}カスタムプロパティや Sass 変数に意味のある名前を付ければ、コメントなしでも意図が伝わります。クラス名も同様で、.box1 よりも .sidebar-widget のほうが説明不要です。コメントを書く前に「命名やコード構造で解決できないか」を考えるのが、結果的にコメント量を適正に保つ方法です。
