ヒューマンリーダブルなフロントエンド設計

この記事はミツエーリンクスアドベントカレンダー2019の8日目の記事です。

フロントエンド設計において「マシンリーダビリティ（機械可読性）」はSEOやWebアクセシビリティの観点からその重要性が度々話題に上ります。Webサイトは特性上、公開して終わりという質のものではなく「素早く」「さまざまな」ユーザーに更新情報を届けることにこそ真価を発揮できるメディアです。マシンリーダブルに設計することはWebサイトの価値を最大限引き出すために必要不可欠な品質指標となります。

しかし、せっかくマシンリーダブルに設計したWebサイトも運用フェーズで品質の維持が難しくなるケースがあります。どんな思想や意図で設計されているのか、コードから読み取ることができない、または読み取りづらく、運用が困難になってしまう場合があるのです。

前述のとおりマシンリーダビリティは言わずもがな昨今のWebサイトの品質指標でありますが、運用フェーズにおいては同じくらい「ヒューマンリーダビリティ」も重要とされるのです。

そこで、新規構築と運用案件の両方の要件を加味し、私が考える「ヒューマンリーダブルな設計」への近道を5点ご紹介します。

設計思想やルールを適切な手段で共有する

一般的に普及しているCSS設計の手法（SMACSS、OOCSS、BEMなど）を忠実に踏襲しているのでしたら作業者も比較的容易に導入できるのですが、設計者独自の解釈が加わったいわゆる「おれおれ設計」だと他の作業者への仕様共有の難易度が上がります。設計思想やルールが正しく伝わらなければ、無法地帯化するのにそう時間はかかりません。

Webサイトは千差万別、ボリュームやユーザーの特性によってさまざまに形があるべきですので、いろんな状況に対応するための「おれおれ設計」は一概に悪ではありません。ですが独自ルールをドキュメントやルール整備という形で作業者に適切に共有することと、メンテナンスし続けることは大変重要であり、大前提となります。

既存のCSS設計の手法を採用するにせよ独自のルールを策定するにせよ、他の作業者に伝えるための確たるガイドラインが必要です。

• 既存のCSS設計の手法を踏襲する場合は、公式のガイドラインを共有する
• 独自ルールを採用する場合は、細部まで仕様を網羅したガイドラインをドキュメントで共有する

前者が圧倒的に引き継ぎコストは削減できますが、大ボリュームのガイドラインを書いてでもオリジナリティを優先したい場合もあるでしょう。いずれにしても「読めば大体の作業ができる」というレベルのルールブックが必要です。

CSS設計の手法を適切に共有することは、ヒューマンリーダブルな設計思想を共有することにつながり、運用を属人化させないための重要なポイントの1つです。

予測可能な整理された命名規則を採用する

たかが命名、されど命名。ID／CSSセレクターやファイル名、変数名・関数名などの命名規則を曖昧にしたまま設計すると、考える時間は想像を超えて多くなることがあります。

一般に普及しているCSS設計の手法は「ジャンル別」「用途別」のように一定のカテゴライズに基づいて命名するものが主流です。カテゴリ単位で管理するため、発生した問題にフォーカスしやすく、かつ作業スコープを絞りやすいメリットがあります。

それらとあわせておすすめしたい命名方法としては、「どんなルールで命名されているか」「何の目的で使用するか」をできるだけ具体的に盛り込むことです。そうして命名することでコードを見た第三者は、その名前が何を意味するかコード上から判断しやすくなります。

<button class="c-btn-conversion">
  <span class="c-btn-conversion__txt">次のページへ</span>
</button>

上記のコードから、

• ページまたはサイトのコンバージョンに関連が深いボタンである
• 「__」で単語をつないでいるからBEMが採用されている
• 「c-」接頭辞を持っているのでFLOCSSが採用されている
• このコンポーネントは汎用的に使用できる
• 「btn」「txt」のように単語を省略する
• 「conversion」のような省略しづらい単語はそのまま使用

のように、1つのクラス名から複数の情報（命名規則）を推測することができます。

予測可能な整理された命名規則を採用することは、第三者が新規コンポーネントを作成したり、スタイル調整する心理的ハードルを下げ、結果として作業コストを抑える働きがあります。

数カ月、数年後の自分に向けて書く

人間が読みやすいコードを書こうと思うと、不必要にコメントを書きすぎたりして思わず冗長になってしまいがちです。

ではコードが冗長にならない適度なレベルとはどの程度なのでしょうか。

あくまでも私個人の意見ですが「数カ月、数年後の自分が見ても理解できるコード」を意識するだけでかなり読み取りやすいコードになると思います。

それだけでも少なくとも、

• コードの並びや構造に規則性を持たせる
• 要点を絞ったコメントアウトで簡潔にメモを残す
• サイトの仕様についてまとめたドキュメントを書く

など、自分自身が要件を見失わないための工夫をするからです。

遊びを持たせる

サイト設計をしていると、いろいろな構造のコンポーネントを作ることになります。 それらのコードをヒューマンリーダブルに書くことで、高いメンテナンス性を確保することができます。

例えば、画像キャプチャのようなビジュアルデザインに対し、何も配慮せずに最小限のコーディングした場合以下のようになったと仮定しましょう。

<h2>ミツエーリンクスのBlog一覧</h2>

<h3>
  <span class="text">フロントエンドBlog</span>
  <span class="subtext">Webのフロントエンドを構成する技術に関連する話題を扱うBlogです。</span>
</h3>

私は後のメンテナンスのため

• div要素で包括する
• クラス名を付与する
• 双方のマークアップ構造を極力合わせる

のような対応をします。

<div class="heading-level2">
  <h2 class="heading">
      <span class="text">ミツエーリンクスのBlog一覧</span>
  </h2>
</div>

<div class="heading-level3">
  <h3 class="heading">
    <span class="text">フロントエンドBlog</span>
  </h3>

  <p class="subtext">Webのフロントエンドを構成する技術に関連する話題を扱うBlogです。</p>
</div>

一見冗長でむだな要素の入れ子があるソースコードに見えますが、

• 見た目はそのままでh2要素をh3要素に変更したい場合、クラス名を変更するだけ
• h2要素にもサブテキストを追加したい場合でも、モジュール構造を変更する必要がない
• サブテキストを見出し要素と区別できる

など、このようにモジュールに遊び（拡張の余地）を持たせるだけで格段にメンテナブルになります。

構造をそろえることでメンテナンス性だけではなく、モジュール仕様の予測しやすさにも一役買ってくれます。

シンプルにしすぎない

フロントエンド設計をしている方は経験があると思いますが、構造やマークアップをつい「シンプルにしすぎてしまう」ことがあります。

コード量削減という観点では一概に悪くないのですが、シンプルにしすぎると反比例して視認性が下がる場合があります。

例えば下記の条件文は、ネストの三項演算で書くことで1行に収まっていますが、初見では見づらさを感じます。

let number = 5;

let text = (number >= 10) ? 'FizzBuzz' : (number <= 5) ? 'Fizz' : 'Buzz';

console.log(text);

下記のように単純にif文で書いた方が、視認しやすくメンテナブルなことがあります。

  let number = 5;
  let text = '';

  if (number >= 10) {
      text = 'FizzBuzz';
  } else {
      if (number <= 5) {
          text = 'Fizz';
      } else {
          text = 'Buzz';
      }
  }

  console.log(text);

おわりに

冒頭でも書きましたが、Webサイトは素早い更新と情報提供が最大の持ち味のメディアです。ですが、長年の運用に耐えうる設計品質に満たない場合、その寿命は短いものに終わってしまいます。延命手段、運用コスト軽減の工夫の1つとして「ヒューマンリーダビリティ」の向上についてご紹介させていただきました。

マシンリーダビリティを考えると同時に、作業者のヒューマンリーダビリティを考えることで、ユースフルで長く愛されるWebサイトに成長すると思います。