HTMLの書き方で差がつく！見やすく保守しやすいコーディング10の基本ポイント

1. インデント・改行ルールの統一

インデントはコードの読みやすさと変更差分の明確化に直結します。弊社ではスペース4つを基本とし、全体の可読性を保っています。

チームで作業する場合は、必ずインデントのルール（スペース or タブ）を明確にし、ツールによる自動整形を導入しましょう。

• Prettier: 保存時に自動でコード整形を行うフォーマッター。VSCodeなどのエディタで簡単に設定可能。
• EditorConfig: .editorconfig ファイルでエディタごとの設定差を吸収し、プロジェクト全体で整形スタイルを統一可能。

例：スペース4つで統一した例

<ul>
    <li>項目1</li>
    <li>項目2</li>
</ul>

---

2. セマンティックなタグとARIAロールの併用

構造を明確に伝えるためには、意味のあるHTMLタグを使用しましょう。さらに、支援技術に対応するためにARIA属性も活用します。

例：ナビゲーション

<nav role="navigation" aria-label="メインナビゲーション">
    <ul>
        <li><a href="/">Home</a></li>
    </ul>
</nav>

例：ハンバーガーボタンのアクセシビリティ対応

<button class="menu-toggle" aria-expanded="false" aria-controls="global-nav" aria-label="メニューを開く">
    <span class="menu-icon"></span>
</button>

• aria-expanded はメニューの開閉状態を示す
• aria-controls は対応する要素のIDを指定
• aria-label でボタンの目的を明示

---

3. クラス設計はCSS設計思想に準拠する

BEMなどの命名規則を導入すると、構造と修飾の区別が明確になり、保守性が向上します。

例：BEM記法（Block / Element / Modifier）・・・BlockとElementの使用例

<section class="news">
    <h2 class="news__title">お知らせ</h2>
    <ul class="news__list">
        <li class="news__item">...</li>
    </ul>
</section>

例：BEM記法（Block / Element / Modifier）・・・Modifierの使用例

<button class="btn btn--primary">決定</button>
<button class="btn btn--secondary">キャンセル</button>

• btn：共通スタイル（Block）
• btn--primary / btn--secondary：バリエーションのModifier

---

4. ネスト構造は浅く保つ

過剰なネストは、保守性・パフォーマンス・アクセシビリティすべてに悪影響を与えます。構造をフラットに保ちましょう。

悪い例

<div>
  <div>
    <div>
      <span>テキスト</span>
    </div>
  </div>
</div>

良い例

<section>
    <p>テキスト</p>
</section>

---

5. 画像のalt属性は文脈依存で最適化

画像に意味がある場合は適切なaltを設定し、装飾目的なら空文字にしてスクリーンリーダーに無視させましょう。

例：情報画像と装飾画像

<img src="map.png" alt="大阪本社の地図">
<img src="line.png" alt="">

altが不要なケース

• 装飾目的の画像
• すぐ隣に画像の内容をテキストで説明している場合

<h2>代表挨拶</h2>
<img src="ceo.jpg" alt="">
<p>代表取締役社長 山田太郎</p>

このような場合、画像にaltを設定せず、テキスト情報にスクリーンリーダーの焦点を当てるのが望ましいです。

---

6. フォームはlabelとinputを確実に紐づける

視認性とアクセシビリティの観点から、label要素とinput要素の紐づけは必須です。

例：for属性での対応

<label for="email">メールアドレス</label>
<input type="email" id="email" name="email">

例：label要素内にinputを含める方法（デザインの自由度が高い）

<label>
    <span>電話番号</span>
    <input type="tel" name="tel">
</label>

この形式は、入力項目全体をボックス化してデザインする際に便利です。

---

7. 見出し構造の論理性を担保する

見出しタグは視覚的な装飾ではなく、文書構造を示すために使います。h1は基本的に1ページ1回、以降は階層順に配置します。

h1は「ロゴ」か「ページタイトル」か？

• 単一ページ構成のサイトでは、ロゴをh1にしても良い
• コンテンツ中心のページでは、記事タイトル・見出しをh1にするのが一般的

sectionと見出しタグの関係 <section> を使った場合、その中の最初の見出し（h2など）がそのセクションのタイトルになります。

<section>
  <h2>サービス一覧</h2>
  <ul>...</ul>
</section>

例：論理的な見出し階層

<h1>サービス</h1>
  <h2>Web制作</h2>
    <h3>デザイン</h3>

---

8. セクションの区切りやDOMブロックにはコメントを

コードの読み手にとって、セクションの役割をコメントで補足することは非常に有益です。

例：構造コメントの使用

<!-- BEGIN: ヘッダー -->
<header class="site-header">...</header>
<!-- END: ヘッダー -->

---

9. id属性の使用は限定的に

idはユニークである必要があり、CSSではなくJavaScriptのフックやアンカー用に限定的に使うのがベストです。

悪い例：汎用的なid名を複数箇所で使う

<div id="box">...</div>

良い例：限定的で意味のあるid

<section id="contact-form">...</section>

---

10. HTMLバリデーションとアクセシビリティ検証を習慣化

開発の最終段階でW3CバリデーターやLighthouse、axeなどでチェックし、構文・アクセシビリティの問題を早期に発見・修正しましょう。

推奨ツール：

• https://validator.w3.org/
• https://developer.chrome.com/docs/lighthouse/
• https://www.deque.com/axe/devtools/

---

まとめ

HTMLは見た目に現れにくい部分こそが品質に直結します。構造の意味を明確に、未来の自分や他の開発者が読みやすく修正しやすいHTMLを意識することが、真のプロフェッショナルなマークアップです。