小〜中規模サイトのフロントエンド・コーディング規約　環境整備編

11794 ワード
Backlog Mac Git 初心者エンジニア Mac テキストリンク

2021/3/15
初めて記事を書いてから３年以上経過してしまったので、
内容を見直ししました。
基本的には大きく変わっておらず、ツールなどの更新を行いました。

弊社の開発部にも人が増えてきたので、いま使っているフロントエンドのコーディング規約をまとめてみました。
ふだんは「開発関係者が10名以下の小〜中規模案件の開発・保守」を請け負うことが多いので、
そこに適した環境整備を目的にしています。

環境整備編が思ったより長くなってしまったので、
HTMLコーディング編・CSS & JavaScript編は別のページにまとめました。

HTML編
CSS・JavaScript編

小〜中規模サイトのフロントエンド・コーディング規約
環境整備編

目的

フロントエンド開発に必要な知識を一通り網羅し、技術を標準化する。

作業前に入れておくツール・アプリケーション(mac)

-- 必要に応じて入れる --

windows 仮想マシンはローカルホストの表示ができるので、QC 対応などで便利です。
動作環境作成参考：かつてmodern.IEと呼ばれていたMac上などの仮想環境でIEやEdgeなどのWindowsブラウザを動かす方法 2020年版

案件管理について

ここで使う「案件」という言葉は、基本的に１つのwebサイトを指しています。
プロジェクトは、「案件」の目的達成のための一連の作業を指します。
（「自社サイト」が案件で、「立ち上げ」や「ユーザ解析機能追加」がプロジェクトになります）

進行管理ツール

  • backlog か GitHub で管理することが多いです。
    backlog をメインで使う場合は、git も backlog に搭載されているものを使います
  • （コメントはこまめに確認しよう）

課題（issue）管理

  • プロジェクトの課題（issue）化は基本、担当が決まった時点で自分で行います
  • 課題名は「プロジェクト名 / 作業区分 / 作業対象 / 作業内容」で名付けます
  • 適切なタグ付けをお願いします（特に GitHub ではあると使いやすい）

例：2021年4月リリース予定のUI改修のフロントエンド構成に関する課題

202104UI改修/要件定義/フロント構成
202104UI改修/実装/トップページ

デプロイ環境

デプロイ先

基本の構成です。案件によって変わることもあります。

  • 本番（公開用）
  • 確認環境（社内・クライアントのみ閲覧）
  • 開発環境（社内・開発部のみ閲覧）

注意点

  • 確認環境以降では、外部サービスも動作確認できるようにしてください
    （SNS共有、計測ツールなど）
  • コード内で絶対パスを記述する際は、タスクランナーなどで
    環境に合わせて可変になるようにしてください

環境変数

  • env ディレクトリを作り、その中に「.env.local」などの
    .env ファイルを作成してください。
  • 「.env」という名前のディレクトリは避けてください
 /
　├ env
　│　├ .env.local
　│　├ .env.development
　│　└ .env.production
　│
　└ .env // 推奨しない！！！
　 　└ .env.production

git について

  • 本番デプロイできるのは master （もしくは main）ブランチのみです
  • 初期開発では feature ブランチで機能開発を行います
  • 複数回リリースがある案件では、 リリース用ブランチを作ります
  • master ブランチでデプロイ時の最新コミットには tag をつけ、
    後からどのコミットが本番に反映されているか確認しやすくしてください

ブランチ構成参考

例：初期開発が終わった後、2021年4月に UI 改修のある案件

master（main）
　├ 202104_UI
　│　├ BKLOG-**_categoryList ... 作業ブランチ（カテゴリリストの改修）①
　│　└ #**_top ... 作業ブランチ（TOP の改修）②
　│
　└ feature ... 初期開発
　│　├ contact ... 作業ブランチ①
　│　└ blog ... 作業ブランチ②
　│
　└ fix ... QC, QA で見つかった課題の対応
　│　└ BKLOG-**
　│
　└ hotfix/#** ... リリース後の緊急対応

backlog を使っている案件ではブランチ名に「{ プロジェクト識別子 }-**」という課題番号、
GitHub を使っている案件では「#**」という issue 番号が入る想定です。

使っている課題管理ツールに通知が飛ぶような形式を推奨しますが、
課題が作られていない、複数の課題の対応をまとめたブランチのなどの場合は
柔軟に対応してください。

ディクトリ構成・ファイル命名ルール

基本は下記のような構成です。CSS, JavaScript はそれらの規約で詳説します。

 /
　├ src/ ... 作業ディレクトリ
　│　├ scss
　│　├ js / ts
　│　├ html / pug / ejs / njk
　│　├ img
　│　└ styleguide ... style guide 生成用ディレクトリ
　│
　├ htdocs/ ... デプロイ用ディレクトリ
　├ build/ ... npm-scripts, シェル
　├ config/ ... フロントエンド環境設定
　├ docker/ ... docker設定
　│
　├ packege.json
　├ docker-compose.yml
　├ README.md
　├ .gitignore
　├ .git
　└ .editorconfig

ファイル命名ルール

ファイル名はすべて小文字にする

<!-- 非推奨 -->
IMG_001.png
TOP.css

<!-- 推奨 -->
img_001.png
top.css

数字・記号から始まる名前をつけない
（パーシャルファイルは "_" から始めます）


<!-- 非推奨 -->
01.png

<!-- 推奨 -->
count_01.png

<!-- 例外 -->
_module.scss
_module.js

連番数字をつけるときは桁数をあわせる

<!-- 非推奨 -->
img_1.png
img_100.png

<!-- 推奨 -->
img_001.png
img_100.png

タスクランナーの使用

  • npm script を使います
  • コマンドの引数でデプロイ/作業環境を切り分けられるようにしてください

npm audit の使用

定期的に npm audit を実行し、npm パッケージのセキュリティチェックを行ってください。
high 以上の警告が出たものは対応対象としてください。
$ npm audit fix でも修正できなかった場合は手動で更新します。

技術採用について

案件特性によって何を利用するか変更します。
普段よく使うもので安定してしまい、
もっと合理的な実装ができる余地を見過さないように気をつけて下さい。

.editorconfig

プロジェクトには editorconfig の設定をお願いします。
既存プロジェクトに追加する場合やフレームワークを使ったプロジェクトには、
元のスタイルを大きく変えないよう設定すると混乱が少ないです。
新規プロジェクトの場合は、下記をベースに必要に応じて拡張してください。

# editorconfig.org
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

作業記録

ブラウザ・サーバ・ローカルストレージなどデータのやり取りが複雑になる場合は、
後で全体が確認できるようにシーケンス図の作成を推奨しています。

後でソースコードを見返したときに「なぜこの実装になっているのか」と
止まったところは何かしらの問題に対する対応処理が入っていることが多いです。
自分で実装した場合はコメントや README.md にメモを残しておき、
他人が実装した場合は（本人がいれば）勝手に修正せず確認を行ってください。

品質保証

納品コードの品質保証のため、下記の確認を行います。

  1. コーダー自身の動作検証（release ブランチプルリク前）
  2. プルリクエスト時のコードレビュー
  3. チームでのQC（master ブランチプルリク前）
  4. 検証会社によるQA（master ブランチプルリク前）

自身のチェック(1) と 他者のチェック(2) は必ず行い、
２人以上に確認をとったコードが公開される ようにしてください。
案件規模によって (3) や (4) を追加します。

コーダー自身の動作検証

検証端末選択の参考　スマートフォン国内シェア：

コードレビュー

  • プルリクエストの送り先は、自分以外で改修内容を把握している人に依頼します
  • プルリクエストを送る前には必ず実機で動作確認を行い、
    ソースコードは構文チェックやテストを通した状態にしてください

プルリクエストの確認ポイントは下記になります。
1. 問題のある箇所（セキュリティ、アクセシビリティ、表示速度など）がないか
2. 実装方法が妥当か
3. クライアントレギュレーション違反を行っていないか
4. 要求されている機能（表示、効果測定など）が実機で提供できているか

コードレビュー依頼の時のサンプルを記載します。
事前知識のない人に依頼する気持ちで、できる限りわかりやすく具体的に
書くようお願いします。

## 対応内容
登録された住所が番外地だった時の対応。
住所の番地が入力されていない場合、利用者情報確認ページ表示時にエラーを出す。
エラー文言は「未入力時」と同一にする（slack での会話参照）。

■ 利用者情報確認（ローカル環境）
http://localhost:8080/order/customer

## 関連issue
#100 ユーザ問い合わせ対応[****]

## 補足
- npm audit で警告のあったモジュールの更新も行いました

## レビュー観点（重点的レビューしてもらいたい点）
- 同じテンプレートを使っているページ（配送先追加、編集）に影響がないか
- ログイン→利用者情報確認 以外の導線でページが表示されることがないか

QC(Quality Control)

QCは、テスト項目書に沿って複数人で動作確認を行うことで品質を保証します。
テスト項目書がない場合は、仕様書通りに実装が行えているかを確認します。
項目書になくても、使ってみて気になったところは backlog などで課題化します。

QC課題化の本文例

TOPで応募ボタン連打したとき画面が正しく遷移されません
------------------------------------------
詳細：
TOPページの懸賞応募ボタンを連打すると応募エラーページに遷移します

備考：
同じページの会員登録ボタンを連打してもエラーページ遷移は発生しません

再現性：
5/5

前提条件：
会員ログイン済みで、懸賞未応募のとき

手順：
1.TOPページにアクセス。
2.会員ログイン
3.TOPページのキャンペーン応募ボタンを素早く連打
4.応募エラーページが表示

期待結果：
応募完了ページが表示されること

アプリファイル名・サイトURL：
　アプリファイル名：
　サイトURL：http://***/***.html
再現端末・OS：E01J(5.0.0), iPhone6(9.3), PC chrome
接続環境：ステージング環境
通信環境：4G、 Wi-Fi
添付資料名：再現動画.mp4

QA（Quality Assurance）

検証会社から指摘が入ったら、backlog などで課題化してください。

納品

zipでファイル納品の場合は、Windows・Mac どちらでも扱えるようにしてください。
何年前の話だ…と感じるかもしれませんが、ツールでパス付きzipを作った場合など、
たまに解凍できない・文字化けが起きることがあります。

また、Mac 特有のキャッシュファイル（.DS_Store）は
納品物に含まれないようにしてください。

Mac 環境では WinArchiver Lit‪e を使うと
文字化けやキャッシュファイルの対応ができるので、おすすめしています。