Appearance
コーディングガイドライン
🚩 概要
このガイドラインは、株式会社ディーゼロで取り扱うウェブサイト制作のために作成されたものです。 ひとりで同時に十数本のプロジェクトに携わる制作において、担当の交代や引き継ぎなどがスムーズにできるように、ルールや方針の統一し、クオリティを担保して確実にウェブページを作成・更新・運用できることを目的としています。
コーディングに大切なこと
- クオリティ
- ビジュアルのクオリティ
- アクセシビリティ
- ダウンロード・レンダリングスピード
- ページパフォーマンス
- メンテナンス性
- 一貫性
- 更新性
- 拡張性
- 影響範囲の把握
- バージョン管理
- 制作スピード
- 制作環境の明瞭化
- テスト・チェックの自動化
- 修正の自動化
🔧 ガイドラインの更新
このガイドラインは日々更新されるウェブの技術やトレンドによって最適化されるべきです。 変更・追記・削除に関しては常に議論されることが期待されます。 集めた意見や議論の結果は、リードエンジニアのもとで更新するか判断されます。 プルリクエストを送ることもでき、その場合もリードエンジニアの判断によりマージされます。
🔰 制作に取り掛かる前に
開発要件・開発環境の確認
次の要件を確定させてから取り掛かってください。原則決まらない状態で進めてはいけません。
- 対象ブラウザ・デバイス
- レスポンシブの要件
- 印刷対応の有無
- 共同作業者との環境の整合
確定させずに取り掛かる場合は、要件の変更による工数の変動を考慮してスケジュールを調整してください。
注意
この判断はコーディング担当者ひとりで判断・解決するべきではありません。 関係者各位とのコミュニケーションを取り、プロジェクトマネージャーの判断を仰いでください。
🌐 対応ブラウザとデバイス
- Windows Edge / Chrome / Firefox: いずれもリリース時点での最新版
- macOS Chrome / Firefox: いずれもリリース時点での最新版
- macOS Safari : リリース時点での最新版とその 1 つ前のマイナーバージョン
- Android Chrome: リリース時点での最新版
- iOS Safari : リリース時点での最新版とその 1 つ前のマイナーバージョン
レガシーブラウザへの対応
上記以外のバージョンおよびレガシーブラウザへの対応は案件に合わせて対応しても構いません。 ただし原則として追加費用が発生するため、クライアントとの契約に基づいて対応してください。
🎯 プロジェクトのルールの最適化
当ガイドラインでは適切でないと判断された部分に関しては、プロジェクト固有の異なるルールに積極的に変更してください。 また、クライアント・代理店・外部パートナーから提示されるガイドラインがある場合はそちらを優先して採用します。 変更した部分に関してはプロジェクトの管理ドキュメントに責任をもって記載してください。
🌞 責任者の選任
コーディングに2人以上の人間が関わる場合、またはパートナーとの共同作業がある場合、コーディングに関する責任者を選任してください。 責任者は次のような役割を担います。
- プロジェクト固有ルールの規定・運用
- コードレビュー
- 工数・見積りのチェック（最終承認は別）
💻 制作環境
エディタ
Visual Studio Codeを推奨します。
また、コーディング時の自動修正・自動警告を有効にするために以下のプラグインをインストールしてください。
他のエディタを利用して構いませんが、次のようなエディタの使用は原則として禁止します。
- 改行コードを変更できない
- 不可視文字を表示できない
- 検索・置換機能がない
推奨エディタ以外の利用に関して、なにかトラブルがあった際の原因がエディタによるものである場合の対応に時間がかかる可能性があることは留意してください。
制作環境の準備
次の環境をPCのローカルに準備する必要があります。
- git
- Node.js
- yarn
Node.jsはプロジェクトのよってバージョンを切り替える必要があるため、バージョン管理ツールの利用してインストールしてください。 管理ツールはVoltaを推奨します。Voltaのセットアップ手順を参考に整備してください。
Gitのインストール
基本的に方法は問いません。 macOSの場合、通常初めてgitコマンドを利用するとXCodeのライセンスに同意する必要があったり、XCodeそのものをインストールする必要があります。 XCodeをどうしてもイントールできない場合、Gitの本家からインストーラを使ってインストールしても構いません。
初期ファイルの準備
現在整備中です
以下は開発中のため、初期ファイルの準備はSlackから@systemにリクエストしてください。
空のリポジトリで次のパッケージを実行します。
zsh
yarn create @d-zero/frontend開発に必要なpackage.jsonやコンフィグファイル、サイト構造の初期ファイルが展開されます。
開発ソースコードと製品ソースコード
HTML/CSS/JavaScirptなどのコードは、開発ソースコードと製品ソースコードに分かれます。
📂
├── 📂 __assets/
│ ├── 📂 htdocs/
│ │ └── index.pug
│ │ ├── 📂 sub-dir/
│ │ │ ├── index.pug
│ │ │ └── sub-page.pug
│ │ ├── 📂 css/
│ │ │ └── style.scss
│ │ └── 📂 js/
│ │ └── script.js
│ └ 📂 _libs/
└── 📂 htdocs/
├── index.html
├── 📂 sub-dir/
│ ├── index.html
│ └── sub-page.html
├── 📂 css/
│ └── style.css
└── 📂 js/
└── script.js__assetsフォルダ配下が開発ソースコード、htdocsフォルダ配下が製品ソースコードとなります。
ドキュメントルート
htdocsフォルダとその中のファイルを最終的にウェブサーバーにアップロードすることになります。 htdocsはドキュメントルートにあたります。 プロジェクトによっては名前を変更しても構いません。 その場合、ビルド設定を変更する必要があります。
製品ソースコードの改変
開発環境のビルドツールによって、開発ソースコードから製品ソースコードに変換がされるため、製品ソースコードを手動で編集・改変することは原則避けてください。
製品ソースコードを納品後にクライアントの手で変更があるケースなどは別途体制などを検討し、プロジェクト個別で対応します。
各開発ソースコードは、次のプリプロセッサやトランスパイラ・ビルドツールを通して製品ソースコードに変換されます。
| 対象 | プリプロセッサ/トランスパイラ/ビルドツール |
|---|---|
| HTML | Pug / 11ty |
| CSS | SASS(SCSS 記法) + PostCSS(Autoprefixer 他) / Vite |
| JavaScript | TypeScript / Vite |
HTMLはHTMLとPugどちらの言語でも記述ができます。 CSSはSCSS記法のSASSのみとなっており、JavaScriptはTypeScriptもしくは最新のECMAScriptのどちらにも対応しています。 それぞれの対応する具体的なバージョンはpackage.jsonや各種コンフィグファイルを参照してください。
ビルド方法
プロジェクト開始時は、そのプロジェクトで利用するパッケージを次のコマンドでインストールしてください。
zsh
yarn installNode.jsのバージョン切り替え
package.jsonに設定されているvoltaの値によって自動的にバージョンが切り替わります。 Volta以外のバージョン管理ツールを利用している場合は、そのツールの設定に従ってバージョンを切り替えてください。
ビルド方法
yarnのスクリプトコマンドつかってビルドをします。
zsh
yarn [オプション]次のコマンドで動作するようにpackage.jsonに設定されています。
| コマンド | 動作 |
|---|---|
yarn build | 全リソースファイルのコンパイルとリントチェック・バリデーションを行います。 |
yarn dev | ローカルサーバーを立ち上げ、全リソースファイルの保存を監視してホットリロードする状態になります。 yarn dでも同様に動作します。 |
yarn release | リリース時のファイルに整形します。全リソースファイルのコンパイルとミニファイ、不要ファイルの削除、リントチェック・バリデーションを行います。 |
主なコーディング手順
yarn devでローカルサーバーを立ち上げる- その状態でコーディングをする
- 一連の作業が終わったら
yarn buildで全体をチェックし製品ソースコードを生成する - コミットする
- リリース時は
yarn releaseを使う
Gitの対象ファイル
現状、テストサーバーのビルド環境の整備不足のため、htdocsフォルダ配下のファイルは.gitignoreに含まれておらずコミットの対象です。
yarn devコマンドの注意点
yarn devでは製品ソースコードは生成されません。 ローカルサーバー上で確認ができているのはローカルサーバーシステムのメモリ上にあるだけです。 コミットの際は必ずyarn buildもしくはyarn releaseをしてください。
治外法権ディレクトリ
クライアントや他ベンダーの制作したソースコードと共存させる場合、開発ソースコードの中ではリンターなどから除外するためにextraterritorialを作っています。
__assets/htdocs/のPugやSCSS、JavaScriptは、それぞれincludeや@use、importを使ってextraterritorialディレクトリのソースコードを読み込み、製品ソースコードに反映させてください。
extraterritorialディレクトリの利用にあたって
あくまでも社内の責任の範囲の外にあるソースコードを共存させるものなので、社内で責任を持ち管理する必要があるコードに関してはこのディレクトリ内で管理しないでください。
プロジェクト固有の規定がある場合は、リンターの側の設定を変えて、extraterritorialディレクトリは使わないようにしてください。
📜 バージョン管理
Git
Subversion
Subversion(SVN)は原則として利用しません。古いプロジェクトで利用していることがありますが、タイミングを見てGitに移行するようにしてください。
📄 テキストファイルに関する基本事項
原則
原則プロジェクトのeditorconfigに従います。
- 文字コード：UTF-8
- 改行コード：LF
- インデント：タブ（幅スペース4つ）
基本的にはエディタやリンターの設定によって自動修正されるようになっています。
Shift-JISほか文字コードについて
案件によっては文字コードがShift-JISなどUTF-8以外の場合があり、エディタで開くと勝手に文字列が変換される場合があるので注意してください。
勝手に文字列が変換されないか確認する方法
※バージョン管理システムが入っていることを前提
- Shift-JIS のファイルを対象のエディタで開く。
- なにも編集せずにそのまま保存する。
- バージョン管理システムで差分を確認する。
- 差分が発生した場合、そのエディタでは編集せず、別のエディタを利用する。
- 発生してしまった差分はバージョン管理システムで元に戻す。
- 発生しなかった場合はそのまま利用する。
- 差分が発生した場合、そのエディタでは編集せず、別のエディタを利用する。
納品ファイルの文字コード・改行コードを変更する
納品ファイルの文字コード・改行コードはビルド設定で変更することができます。詳細はHTMLガイドラインを参照してください。
留意点
- メタ文字・制御文字は削除すること
- 行末の無駄なスペース・タブをつくらないこと
- 必要なとき以外は全角スペースを挿入しないこと
✅ 検証とテスト
ブラウザチェック
対象とするブラウザやデバイスでの検証を行ってください。
iOS Safari
iOS Safariの検証は、検証機を使うか、もしくはXCodeのSimulatorを利用してください。
Android Chrome
Android Chromeの検証は、検証機を使うか、もしくはAndroid StudioのAndroid Emulatorを利用してください。
チェックツール
チェックツールを利用して問題の早期発見と修正を行ってください。
各種リンター
リンターが設定されています。エディタ上の警告、ビルド時・コミット時のリンターの警告を無視せずに修正してください。
axe DevTools
アクセシビリティの問題を検出するためにAxeを利用してください。ブラウザ拡張機能のaxe DevTools - Web Accessibility Testingを利用して、localhost環境の時点でもチェックをしてください。指摘内容については基本的には修正をしてください。