【HTML】良いコードの書き方のポイントをWeb制作会社の現役コーダーが解説します

HTMLなどのコードを書いていて「良いコードとは何か？」と思ったことはありませんか？

良いコードは高いスキルがなくても書けます。逆に言うと、「難しいコード＝良いコード」ではありません。

ポイントは「どれだけ見る人のことを考えられるか」。誰にとっても見やすいコードにするには、押さえるべきポイントがいくつかあります。そのポイントをまとめて知りたくありませんか？

今回はHTMLコードをベースに良いコードの書き方について解説します。エンジニア目線で「お、いいコード！」と思わせるポイントをまとめたので、ぜひ最後までお読みください。

ちなみに筆者は、クーシーでコーディングチームのリーダーをしています。私の紹介記事がありますので、興味ある方はこちらもどうぞ。

個人でもチームでも、ビジネスの基本としてPDCAをしっかり回す／フロントエンドエンジニア・土田玲央

Web制作現場における良いコードとは

Web制作現場における良いコードとは、「分かりやすさ、実用性、汎用性が考慮されたコード」です。

難しいコードが書けるなら、少なくともコーダーとしてのスキルは高いと言えます。しかし、他の人が見て分かりづらければ、それは決して良いコードではありません。

万人に分かりやすくなくてもいいですが、自分と同じぐらいのスキルの人、もしくは自分より少しスキルが低い人でも分かるコードでなければ、実用性や汎用性は不十分です。

「良いコードとは分かりやすいコード」
「分かりやすいコードは実用性や汎用性がある」
シンプルにこう言い切っていいでしょう。

分かりやすさを決めるのは自分以外の人です。どれだけ自分以外の人のことを考えて書いているか。そんな目線で、良いコードのポイントについて解説していきます。

良いコードは見た目が9割

私はWeb制作会社のコーディングチームのリーダーとして、他人のコーディングをチェックしています。その時にまず見るのが「コードの見た目」です。コードそのものの見た目なので、ブラウザ上での見え方とは関係ありません。

では何のためにチェックするのか。それは「作業の質」が見たいからです。作業が丁寧か雑かは、コードを見ただけでわかってしまいます。

主な見た目チェックポイントは以下のとおりです。

• ソースインデントが揃っているか
• 適切な改行が入っているか
• 適切なclass名がついているか
• 適切なコメントアウトが入れてあるか

どうですか？　どれも高いスキルを必要としませんよね？

それぞれ具体的に見ていきましょう。

ソースインデントが揃っているか

ソースインデントとは、構造を見やすくするためにコードの先頭に空白を挿入することです。

ソースインデントが揃っていればコードは見やすいですが、揃っていないと見づらくなります。例を見てみましょう。

まずは良い例。ソースインデントが半角スペース2つで統一されていて見やすいです。

<div class="hoge">
  <h2 class="fuga">タイトル</h2>
  <p class="piyo">テキストテキストテキストテキスト</p>
  <figure class="hogera">
    <img src="hogera.png" alt="" />
    <figcaption>hogera</figcaption>
  </figure>
</div>

悪い例は、ソースインデントが統一されておらず、ご覧の通りガタガタで見づらくなっています（ちょっと極端にやっていますが）。

<div class="hoge">
    <h2 class="fuga">タイトル</h2>
 <p class="piyo">テキストテキストテキストテキスト</p>
<figure class="hogera">
    <img src="hogera.png" alt="" />
    <figcaption>hogera</figcaption>
  </figure>
</div>

ここでは半角スペースを使いましたが、ソースインデントは「タブ」でつけても構いません。また、1ソースインデントの幅（半スペ / タブの個数）も決まりはありません。

重要なのは、「コード全体で統一のルールでつけられているか」です。

エディタによっては、半角スペースを使ってもタブを使っても同じソースインデントの幅で表示されることがあります。それはあくまでエディタの仕様によるものです。他の人の環境だったら、見た目が崩れるかもしれませんよね？　そこまで考えられると、統一のルールで書くことの重要さが理解できるはずです。

適切な改行

改行もまた、ソースインデントと同じく、コードの構造を見やすくする重要なポイントです。「必ずここで改行！」というルールはありませんが、コード全体を通して一定のルールで改行が入っていないとコードが見づらくなります。具体例を見てみましょう。

良い例は、各要素ごとに改行されていて見やすいです。

<div class="hoge">
  <h2 class="fuga">
    タイトル
  </h2>
  <p class="piyo">
    テキストテキストテキストテキスト
  </p>
  <figure class="hogera">
    <img src="hogera.png" alt="" />
      <figcaption>
        hogera
      </figcaption>
  </figure>
</div>

これに対して、悪い例は改行に一貫性がなく見づらいです（極端にやっています）。

<div class="hoge"><h2 class="fuga">
  タイトル
  </h2><p class="piyo">テキストテキストテキストテキスト</p><figure class="hogera">
    <img src="hogera.png" alt="" /><figcaption>
    hogera
    </figcaption>
  </figure>
</div>

適切なclass名

class名はどう付けても機能的には問題ないですが、見やすさを考えると一定の作法があります。多少Webのリテラシーや経験値にも関わってきますが、高いスキルは必要ありません。

まずは良い例。わかりやすい英語で付けられていて、何に付けられたclass名かが一発でわかります。

<div class="box">
  <h2 class="title">タイトル</h2>
  <p class="text">テキストテキストテキストテキスト</p>
  <figure class="img">
    <img src="img.png" alt="" />
    <figcaption>キャプション</figcaption>
  </figure>
</div>

悪い例は、ハコ、ミダシなど、日本語がそのままアルファベット表記になっています。日本語はアルファベット表記と相性が悪く、読みづらいですよね。

<div class="hako">
  <h2 class="midasi">タイトル</h2>
  <p class="bun">テキストテキストテキストテキスト</p>
  <figure class="zu">
    <img src="hogera.png" alt="" />
    <figcaption>hogera</figcaption>
  </figure>
</div>

適切なコメントアウトの使用

コメントアウトとはソースコード上に残すメモみたいなもので、ブラウザ上には表示されません。書かないといけないモノではないですし、クローラーからすれば邪魔な存在かもしれません。わざわざ書くのであれば、そこには意図や意味があってほしいです。

良い例では<!-- // box -->のコメントアウトによって、1ブロックの要素が明確化されています。ソースインデントと同じく、HTMLコードの構造がさらに見やすくなりました。

  <!-- // box -->
  <div class="box">
    <h2 class="title">タイトル</h2>
    <p class="text">テキストテキストテキストテキスト</p>
    <figure class="img">
      <img src="img.png" alt="" />
      <figcaption>キャプション</figcaption>
    </figure>
  </div>
  <!-- box // -->

一方で悪い例では、コメントアウトが個人的なメモになっており、客観的に見てあまり意味がない情報です。

  <!-- hakoだと恰好悪いからboxにしてみた -->
  <div class="box">
    <h2 class="title">タイトル</h2>
    <p class="text">テキストテキストテキストテキスト</p>
    <figure class="img">
      <img src="img.png" alt="" />
      <figcaption>キャプション</figcaption>
    </figure>
  </div>

コードの見た目について、いくつか例を挙げてみました。これらをクリアできているだけでも、十分良いコードに見えます。逆に難しいコードが書けても、ここがクリアできていないと残念なコードです。

次は少し踏み込んで、HTMLコードの質を見ていきます。

大まかなHTMLコードの構造のチェックポイント

大まかなHTMLコードの構造は、以下の点をチェックします。

• HTMLバリデーションチェック（ツール）
• アウトラインのチェック（ツールと目視の両方）
• 適切なHTMLタグ仕様

若干の知識が必要となってきますが、コーダーとして基礎レベルの知識ですので身に着けましょう。

HTMLバリデーションチェック

HTMLバリデーションチェックとは、HTML言語として正しい使い方ができているかどうかのチェックです。

HTML4から5になり、HTMLタグの使い方はかなり緩和されましたが、それでもルールはあります。言語として正しい使い方ができていなかったとしても、最近のブラウザは優秀なので、ブラウザでの見た目には関係ありません。車で言えば、走る止まる曲がるは問題ないけど車検は引っかかるといったところです。

バリデーションチェックは、以下のツールでサクッと確認できます。HTMLを貼り付けて「Check」をクリックするだけです。

アウトラインのチェック

HTMLのアウトライン、すなわち階層構造ができているかの確認です。これはGoogle Chromeの拡張機能「HTML5 outliner」を使えば一瞬で確認できます。

HTML5 outlinerの使い方はこちらの記事をご覧ください。

【Chrome 拡張機能】Web制作の現場で選ばれているおすすめ12選｜制作編

これだけでは不十分なところがあるので、私はブラウザのデベロッパーツールで目視チェックもします。

適切なHTMLタグ

アウトラインが適切でも、中の要素がきちんとマークアップされていなかったら残念です。アウトラインの中の要素も、コンテンツとして意味のあるHTMLでマークアップされているかチェックします。

良い例では要素の意味に合わせてタグが使い分けられています。「section」という大きな箱の中に見出し「h2」と内容「p」があって、、、という具合です。

  <section>
    <h2>タイトル</h2>
    <p>テキストテキストテキストテキスト</p>
    <figure>
      <img src="img.png" alt="" />
      <figcaption>キャプション</figcaption>
    </figure>
  </section>

悪い例では、divタグが多用されています。これだと、どんな要素なのかわかりません。アウトラインの中の要素が意味のないHTMLでマークアップされると、こうなります。

  <section>
    <h2>タイトル</h2>
    <div>テキストテキストテキストテキスト</div>
    <div>
      <img src="img.png" alt="" />
      <div>キャプション</div>
    </div>
  </section>

さらに高度なコードの質のチェックポイント

もう少し踏み込んでコードチェックするとき、見るのは以下の2点です。

• 一定のルールで統一されたclass命名かどうか
• 画像の属性値（alt,width,height,loading）が付いているか

これらは「細かい部分を気にしてコーディングしているか」がわかるポイントです。

一定のルールで統一されたclass命名かどうか

一般的に、class名の命名規則には「記法」と「CSS設計」の2軸があります。

記法

class名の表記ルール。メジャーな記法は以下の4つです。

CSS設計

CSS設計とは、CSSのメンテナンス性や作業効率化を考慮したclass名の付け方の規則です。メジャーなCSS設計には以下の3つがあります。ここでは簡単な説明に止めますので、詳細は各公式ページをご覧ください。

ちなみにCOOSYではコーディングガイドラインとして「キャメルケース」と「BEM」を採用していますが、必ずしもメジャーな「記法」と「CSS設計」を採用する必要はありません。何のルールにも属さない、自分独自のルールであってもいいのです。

大事なのは一定のルールで統一されていること。
そしてそのルールが分かりやすいということ。

少なくともコード上から何かしら一定の法則性が見えてこないようでは、分かりやすいルールとはいえません。それを自分で作るのは大変だから、既存のルールを使うわけですね。


良い例として、キャメルケースとBEMを使った書き方を挙げます。知っている人なら、「あ、キャメルとBEMだな」とわかって見るのが楽になるはずです。

  <!-- // box -->
  <div class="box">
    <h2 class="box__mainTitle">タイトル</h2>
    <p class="box__text">テキストテキストテキストテキスト</p>
    <section class="box__section">
      <h3 class="box__section__subTitle">タイトル</h2>
    </section>
    <figure class="box__img">
      <img src="img.png" alt="" />
      <figcaption>キャプション</figcaption>
    </figure>
  </div>
  <!-- box // -->

一方で、ルールが統一されていないclass命名だと、法則性がないので見るのにちょっと頭を使わなければなりません。見る人に負担をかけてしまうのです。

  <!-- // box -->
  <div class="box">
    <h2 class="box__mainTitle">タイトル</h2>
    <p class="box-text">テキストテキストテキストテキスト</p>
    <section class="box-section">
      <h3 class="box-section__sub-title">タイトル</h2>
    </section>
    <figure class="boxImg">
      <img src="img.png" alt="" />
      <figcaption>キャプション</figcaption>
    </figure>
  </div>
  <!-- box // -->

画像の属性値（alt, width・height, loading）

画像の属性値はついつい抜けてしまいがちです。後から対応するとなると非常に面倒なので、そうならないようにします。追加対応を不要にして、実用性と汎用性のあるコードにしましょう。

alt属性

alt属性は画像の代替テキストを設定する属性で、HTML4以降必須の属性です。書いておくことで、画像の内容をクローラーに伝えられ、画像検索で上位表示が狙えるようになります。

なおalt属性を書かないと、HTML5バリデーションチェックで引っ掛かります。

width, height属性

width, height属性は画像の幅・高さを設定する属性です。画像の幅や高さはCSSによる制御がメインであり、無くても支障がないためつい忘れてしまいがちですが、書く意味はちゃんとあります。

書いておくと画像レンダリング中のカクつき動きを防ぐことができるほか、クローラーのページ評価を上げることもできるのです。書いていないとPageSpeed Insightsでお叱りを受けますので、ページ評価を上げるためにもきちんと書いておきましょう。

loading属性

loading属性は画像の読み込みのタイミングを制御します。

• lazy：遅延読み込み
• eager：優先読み込み
• auto：遅延 or 優先をブラウザ側で自動判断

これもページの評価に関わっており、きちんと整備しないとPageSpeed Insightsでお叱りを受けます。

loading属性は以下の記事でも解説していますのでご覧ください。

サイト高速化の1番の近道は軽量化！おさえるべき4つの項目

まとめ

今回はHTMLコードをベースに、「良いコードの書き方のポイント」について解説してみました。

ある程度のスキルと自信がついてきたコーダーは、「複雑なコードを俺は書けるぜ！」と、ついつい自分のスキルをひけらかすような作業をしがちです。そして今回ご紹介したコードのマナーのような部分は、「どうでもいい！」と、おざなりになってしまいがちです。
はい、分かります。私もそんな時期ありましたから（苦笑）。

この記事を読んだあなたは、もうそんなふうに考えないはず。分かりづらいコードこそレベルが低いのであり、分からない人のレベルが低いのではありません。

「どれだけ自分以外の人を考慮できるか」は、HTMLコードに限らずどんな言語のコードでも言えることです。いや、作業やコミュニケーション、サービスなどすべてにおいて重要と言っていいでしょう。

本記事が「良いコード」を心がけるきっかけになれば幸いです。