失敗から学ぶ、コーディングする前に設計しておきたいだいたい4つのこと

過去の私へ

いいか！！！！！！設計しないでいきなりコーディングしたら！！！！！
爆死するからな！！！分かったか！！！！！！！！！！！

そうです。コーディングする前に色々こちらでルールを決めないと、
破綻、爆死をするのです。

そんな私の失敗から学んだことをこちらに記述していきます。

この記事を見て参考になるかなという対象の方

• マークアップエンジニア
• 0->1を作ることが多い方
  • クライアントワークとか、新規事業とか
• 設計をよくやってるよという人
• マサカリ担いだ金太郎

コーディングする前に決めておくこと5選

1. 事前に合意をしておこう。サポート対象の環境

これやらなかったら、納品後に「この環境で動かないんだけど〜〜」とデバッグ地獄を見ました。
クライアントに聞くでもいいですし、こちらから言っちゃうのも可です。
以下を洗い出します。

• PC
  • Windows
  • Mac
• スマホ
  • Android
  • iOS
• ブラウザ
  • Mac
    • Safari
    • Firefox
    • Chrome
  • Windows
    • Edge
    • Chrome
  • Android
    • Chrome
  • iOS
    • Safari

IEいつまでサポートするのかなぁ。。。

2. 運用を見据えてしっかり決めようディレクトリの基本構成

決めずに当てずっぽうでやったら、運用に渡した際に「分からない」とか、ファイルのバッティングとか起きました。辛い。

リソースファイルをどこに置くか、グローバルのファイルをどこに置くか等を決めます。
ディレクトリの命名は、運用する人がわかりやすい命名にするとよいと思われます。

よく使うディレクトリ名は以下

• htdocs
  • ドキュメントルートの場所。コンパイル後
• src
  • ソースファイルを置く場所。scssとか置いてる。コンパイル前
• assets
  • 画像、スタイルシート、js等リソースファイルを管理する場所。
• shared_file
  • サイト全体共通で、サブドメインのサイトにも配布、読み込みするファイルを管理するところ。

0からベースを作る場合

運用がしやすいように、誰が見てもわかりやすいディレクトリ名にするとよいと思います！（すごく苦手）

公開されているサイトの一部をリニューアルする場合

現在公開されているサイトの一部分のみに手を加える場合は、
公開されているサイトになるべく影響を与えない形で制作を進めなければなりません。
以下の場合がたまーーーーにあり、結構複雑になることがあります。

• 複数の会社がカテゴリごとに担当をしている
• サイト全体に挿入されているヘッダー、フッターのリニューアルを頼まれた（しかも現行の仕様と違う挙動をする）

すでにクライアント側や、公開されているサイトの制作ガイドライン等がある場合はそれに従えばいいのですが、
無い場合であったり、制作ガイドラインが古い場合等は調査が必要になります。

既存サイトの調査をする

その際にチェックする項目は以下

• 現在のディレクトリ構成
• サイト内のパスルール
• フォントサイズの指定方法
• 命名ルール

上記を調査した上で、ディレクトリ設計であったり、命名規則等を決めます。

3. ベースを作ろう命名ルール

画像の命名や、class属性の命名等決めておかなければ、

• 他の人がコーディングをする際にclass属性の命名の読み解きが辛い
• 横展開しづらい
• 画像の差し替えが辛い
• スタイルのバッティング

が起こり、メンバー含め辛い目に遭遇します。
私がclass属性の命名で参考にしているのはBEMです。

BEMの命名やその他のCSSアーキテクチャについては以下を参考にしてください。
https://qiita.com/tsugu_maru_san/items/e3c9a8fd64c6500b59b8

BEMだと、BlockとElementの間は__(アンダースコア2つ)Modifierの区切りは_(アンダースコア1つ)、
単語同士の区切りは-(ハイフン1つ)と冗長かつちょっとややこしいので、私は以下にアレンジしています。

• BlockとElementの区切り：_(アンダースコア1つ)
• Modifireの区切り：-(ハイフン1つ)
• 単語が2語以上連続する場合：キャメルケース

例
block_elementElement-modifier

画像の命名については種類別に接頭辞に該当のものを記述しています。

• コンテンツ用の画像
  • img_
• サムネ用の画像
  • thumb_
• メインビジュアルや、Heroイメージで使用する画像
  • mv_、hero_
• アイコン用の画像
  • ico_

4. 案件ごとにルールを明確にしよう。呼び出しパスのルール

これ決めずに適当に進めてたら、
「このページでは絶対パスだ！このページでは相対パスで書かれている！どっちが正だ！」
とコーディングする人を混乱させます。

また、パスのルールが混在していると、
A「このページに遷移できないんだけど、バグ？」
B「いや、そこはうちで担当していないカテゴリへの遷移でファイルももらってないので遷移はできないです。ルート相対パスで記述しているのでまぁそうなりますね。」
A「ちゃんと遷移できるかのチェックがしたいのに。。。問題の切り分けがしづらいなぁ。。。」

と、検証段階で問題の切り分けがしづらかったり、
コーディングをした本人の意図しか反映されていない保守しづらいものになります。
パスのルールはしっかり決めましょう。

呼び出しパスには大きく「絶対パス」と「相対パス」の2種類があり、
それぞれメリットとデメリットがあるので、案件の内容に合わせて採用すると良いです。

絶対パス

任意のファイルの位置を最初から最後まで記述する方法。
httpやhttpsから始まります。

例

<div class="image">
  <img src="https://picsum.photos/id/237/200/300" alt="">
</div>

メリット

• ファイルがアップされていたらどの環境でもリンク切れを起こさない

デメリット

• 画像の差し替えが発生した場合に、検証環境で「画像が差し変わったか」を検証することができないので本番までドキドキすることになる
• ドメインの書き換えやURL変更等のときに辛くなる

相対パス（自ページ相対）

表示している自分自身（=今いる場所）を基準とし、自分自身からファイルのパスをたどる記述方法
./や../で始まるのが特徴です。

例

<div class="image">
  <img src="../images/hoge.jpg" alt="">
</div>

メリット

• ルートディレクトリから丸っと別の場所に移行する際に、パスの書き換えが不要になる
  • そのディレクトリ内で完結する場合や、ディレクトリの構成が変更しない場合に限る
    • 例：/jp/assets/images/hoge.jpgが/content/jp/assets/images/hoge.jpgになっても/jp/以下の構造は変わらないので、パスの書き換えが不要

デメリット

• 今いる場所から辿る形式になるので、考えるのがしんどい
• ディレクトリ内の構成が変更になった時にパスの書き換えが必要になる

相対パス（ルート相対）

ディレクトリのルートを基準とし、任意の場所までファイルを辿る方法。
/から始まるのが特徴

例

<div class="image">
  <img src="/assets/images/hoge.jpg" alt="">
</div>

メリット

• サイト全体どこでも同じ表記なので、シンプルかつわかりやすい
• サイトドメイン名自体を変更しても影響がない
  • （ドメインから指定していなければ）
• 開発環境・テスト環境・本番環境の移行も問題なし

デメリット

• ルートにしている階層に変更があった（階層が1つ下がった）場合にパスの書き換えが必要

今の私へ

最適解かはわからんけど、今後もいろんなもの作っていこうな！！！！！！！！！！！