リーダブルCSS 誰が読んでも分かりやすいCSSを書くために

他人や過去の自分が書いたCSSはとにかく読みづらい。
それはCSSの言語の仕様上、仕方のないことかもしれません。

CSSは他者に実装意図を伝えづらい言語です。
他の言語であれば、作業者が名前を付けられる部分や、処理を分割する自由度があるなど、人間に理解しやすいリーダブルなコードにする余地があります。

しかしCSSではその余地が少なく、「このコードがどういう意図で書かれたのか？このコードは消しても問題ないのか？」を理解しづらくなりがちです。

そんな難しいCSSを少しでも分かりやすく、リーダブルなコードにするために工夫できるポイントをこの記事で紹介していきます。

※ 本記事ではBEMやOOCSSといった命名規則、アトミックデザインなどの考え方、CSSinJSやWebComponentsなどの技術については触れません。それらの規則や技術を使うかどうかに関わらずに使える抽象的な考え方を紹介します。

class名の付け方

省略しない

まず前提として、class名に使う単語は省略すべきではありません。

リーダブルなコードとはすぐに理解できるコードです。
その前提から考えると「この省略された単語がなんなのか？」を考える時間が発生してしまうのはよくないことです。

しかしそうなると「ButtonをBtnと略すように、よく使われる省略でみんながすぐに分かりそうなものなら問題ないのか？」と、疑問も発生してきます。
確かにこの例ぐらいであれば問題ない気もしますが、「みんながすぐに分かりそう」の境界線はどこにあるのでしょうか？
その境界線が明確でない以上、未来の誰かにとって分かりづらくなってしまう可能性がある省略は全て避けるべきだと思います。

以下は筆者が実際に見かけた、何の略なのか頭を抱えてしまったコード例です。
どれも元の単語が予想できないわけではありませんが、いくつか候補が考えられるなどして迷ってしまいました。

特徴的な単語を使う

class名には汎用的な単語ではなく、できるだけ特徴的な単語を使うべきでしょう。

Wrapper、Inner、Box、、といった汎用的な単語は多くのケースで使えるので、ついつい便利に多用しがちです。
しかしその単語選択は本当に適切でしょうか？

例えば下記の要素にclass名を付けるとします。

以下は汎用的な単語を使った例です。
CSSファイルで .Inner と見た時に、どこを指しているかパッと判断できるかは怪しいでしょう。

一方、特徴的な単語を使った例が以下です。
.Contentからは「記事の中身の部分かな？」とアタリをつけられるのではないでしょうか。

もちろん特徴的な単語を見つけられないケースもありますが、その要素の実態を適切かつ明確に表す単語を探す努力をすることで、分かりやすいコードに近づけるでしょう。

コメントの残し方

コードのわかりやすさにおいてコメントは非常に重要ですが、CSSにはコメントをあまり残さない人も多くいます。

その理由を聞くと「どこにコメントしていいか分からない」「どんなコメントを残すべきか分からない」といった回答が多かったです。

そんな方のために、コメントを残すべきところ、どんなコメントを残すべきかの知見を紹介していきます。

どこにコメントをすればいいか分からない

この疑問への回答は非常にシンプルで「迷うところには全て残すべき」です。

今コードを書いているあなたが「ここは分かりづらいかも」「他の人が見て分かるかな？」と感じた部分は、後で見たら100%分からないですし、他の人が見たら100%分かりません。

未来の自分も、自分以外も信用せず、迷ったらコメントを残しましょう。

とはいってもコメントすべき場所の指針がないと分かりづらいと思いますので、自分がよくコメントを残す場所を例として記載しておきます。

ブラウザーごとのバグに対応したところ
- 一部のブラウザーのための記述は後で見る人にとっては理解しづらく、不要だと判断して消してしまうケースがあります
擬似要素を使っているところ
- 擬似要素は自由度が高く、CSSを見るだけだと何をしているか判断しづらいです
JSと連携しているところ
- CSSだけで完結していない部分は構造が把握しづらいです
処理をもっと美しく書けそうなところ
- あまりうまく書けていないなと思うところにコメントを残しておくことで、後で見た人などが「もっとシンプルに書けそうだけど、なんでこうなっているんだろう」となった際にリファクタリングしやすくなります
珍しいCSSプロパティーを使っているところ
- 使う頻度が高くないCSSプロパティーは見る人によっては知らないこともありますし、知っていても詳細な挙動がイメージできないことがあるため、コメントを残しておくと安心でしょう

実際にコメントを残すイメージは以下のようになります。

コメントの仕方例


.hoge {
  width: 100%; /* この記述がないとIE11ではみ出す */

  /* 吹き出しの三角部分を作成 */
  &::before {
    content: "";
    ~ 略 ~
  }
}

.fuga {
  /* TODO:absolute指定で無理やり右に寄せているが、もっといい方法ありそう */
  posititon: absolute;
  right: 0;
}

.piyo {
  filter: blur(5px); /* filterを使ってぼかしをかけている。IEには効かないが許容 */
}

.hogehoge {
  display: none; /* デフォルトでは非表示、JSで表示する */
}

どんなコメントを残すべきか分からない

次はどんなコメントを残すべきかを考えていきましょう。
コメントの基本は「何も知らない第三者が見てもパッと理解できるものにする」ことだと思います。

例えば以下のようなコメントはどうでしょうか。

分かりづらいコメントの例


// 暫定的な対応

これを他人が見たら「暫定的？」「修正が必要なのか？」と迷ってしまいそうです。
以下のようなコメントだとだいぶ分かりやすくなります。

丁寧なコメントの例


// TODO：初期リリースで時間がないためabsoluteを用いて無理やりに配置
// もし画像サイズが変わるケースが今後出た場合には崩れるので、その際には要修正

試したことや、うまくいくかもしれないアイデアを追加で書いておくのも場合によっては有効でしょう。

さらに情報を増やしたコメントの例


// 試したがダメだったこと：flexを使うとモダンブラウザーではうまくいくが、IE11ではみ出す
// うまくいくかもしれないこと：flex-growの値を適切に設定すればできるかも？

ここまで丁寧に書くと「コメント量が多すぎて見づらい！」「残タスクは別のツールで管理するべきだ」という批判もあるでしょう。

自分は以下のような理由から、コメントを多めにコードに残すべきだと考えていますが、どこまでコメントを手厚くするかはプロジェクト内で事前に相談しておくと良いでしょう。

「コメント量が多すぎて見づらい！」
- → コメントを読む時間が多少増えても、情報が増えて、同じような試行錯誤に時間をかけなくて済むなら、多めにコメントを残すべき
「残タスクは別のツールで管理するべきだ」
- → 対応の温度感によってはその通りです。急いで対応しなくてもいいものであればコード内にコメントで残すことも良いと思います

コメントのあるべき姿

コメントは不要であれば後で消すことは容易です。
しかし、理解できないコードがあっても、後でコメントを追加することは簡単ではありません。

そのため、迷ったら多めに書いておく、丁寧に書いておく、という方針が長期的に運用するプロダクトにおいては正しい姿勢ではないでしょうか。

変数とmixinの使い方

CSSが非常に読みづらいのは他の言語に比べ、実装者が命名できる部分が少ないからだと思っています。
他の言語であれば変数や関数に名前を付けることで、数値や処理の意味合いを明示することが容易です。

コードの表現力に乏しいCSSではありますが、Sass、PostCSS、StyledComponentsなどを使えば変数や関数を利用できるので、積極的にそれらのメタ言語を用いて、CSSを分かりやすく書いていきましょう。

変数の使い方

変数はどこまで使うべきでしょうか？
自分はCSSのバリューで数値が出てくるものは全て変数化することを推奨しています。

ぱっと見では、文字量が増えているため読みづらさを感じるかもしれません。

ですが、変数化していない場合に比べて情報量は非常に増えており、「ここはカラムのサイズに合わせているんだな」や「これは要素の重なり順として上の方にしたかったんだな」などのニュアンスを感じ取ることができます。

このように変数化しておくことで、コードの意図が残るようになり、次の人がリファクタリングをする際などに助けになることは間違いありません。

「さすがに全ての値を変数化するのは大変だな、、」と感じた場合は、まずは意図が伝わりづらくマジックナンバー化しやすいサイズ関係の値（widthとheight）、重なり順が管理しづらくなりやすいz-indexなどを変数化してみるのがオススメです。

mixinの使い方

CSSにおけるmixinをざっくり言うと「記述をまとめたもの」で、よく使う処理をひとまとめにしておき、読み込むだけで使いまわせるようにしたものです。
他の言語における関数のように引数を渡すことなども可能です。

※ 実際に使えるmixin集はこのブログの別記事で紹介しております。
使いまわして楽しよう！CSSの便利mixin集 | FE-Designer

コードを読みやすくするためにどこまでmixinを用いるかは非常に判断が難しいです。

flexを使って要素を上下左右中央に配置する例を考えてみましょう。
mixinを使わずに普通に書くと以下の通りです。

mixinを使わずに書いた場合


.hoge {
  display: flex;
  align-items: center;
  justify-content: center;
}

mixinを使うと例えば以下のようになるでしょう。

mixinの定義（定義ファイル内）


@define-mixin setCenterByFlex {
  display: flex;
  align-items: center;
  justify-content: center;
}

mixinの適用（個別のコンポーネント内など）


.hoge {
  @mixin setCenterByFlex;
}

mixinにすると、mixin名の分だけ情報量が増えます（上記の例だとsetCenterByFlexの部分）。
その結果、何をするための記述なのかが理解しやすく、リーダブルなコードに近づいたと考えることができそうです。

「では全てのコードをmixinの中に入れていけばいいのか？」というと、そうとも言えません。
極端な例ですが、以下のようなmixinは冗長なだけで、コードを分かりやすくするものではありません。
むしろ理解するのに時間がかかってしまうでしょう。

mixinの定義（定義ファイル内）


@define-mixin setTextCenter {
  text-align: center;
}

「どこまでmixinにすればいいか」に明確な基準は設けづらいですが、自分の場合は以下のような軸で判断を考えています。

あまり使わないハック的な実装かどうか
- 見慣れない記述の場合は、実装意図が把握しづらいので、何のための記述なのかを名前に込めてmixin化
記述の量が多いか
- 1つの目的のために10行にも及ぶような記述をしている場合は、理解が難しくなるので、記述をまとめて分離するためにmixin化

mixinを使わずコメントを残す方が良いケースも多く、使いどころが悩ましいことも多いですが、使いながらちょうどいい適用範囲を探ってみてください。

※ 実際の運用では、CSSの読みやすさの観点だけではなく、コードの実装速度やメンテナンス性の高さなども考慮して判断する必要があります。

変数とmixinは便利だが、、

変数とmixinを適切に用いることでコードを分かりやすく可能ですが、注意点も存在します。

それは変数とmixinを定義しているのに適用していないところが増えてくることです。

用意してあるのに使っていない場合、実装者以外が見たら「あえて使っていないのかな。。変数に置き換えるとダメなのかも？」と考えざるを得ません。
また一括置換する際などに置換漏れが発生して表示崩れなどにつながるかもしれません。

使われない変数やmixinは混乱を招くだけですので、プロジェクトメンバーがきちんと認識して使いこなせる範囲内で定義をするようにしましょう。

リーダブルなCSSを書くための心構え

読みづらくなりがちなCSSを分かりやすく、リーダブルにするために工夫すべきポイントについて紹介してきました。

最後に、リーダブルなCSSを書くために最も大切な心構えをお伝えします。

それは想像力を働かせることです。

「数カ月後の自分は理解できるだろうか」
「別の会社やプロジェクトから人が来た時に理解してもらえるだろうか」
「あまりCSSに慣れていないエンジニアにも優しいコードだろうか」

このような疑問を自分に投げかけ、コードをどうすれば分かりやすくできるのかに想像力を働かせることができれば、きっとあなたの書くコードは良いものになっていくはずです。

この記事をシェアしてくれると小躍りします