概要
スタイルガイドとは「キレイに揃える」ためではない。
それは**“コードの設計意図を伝達可能にし、変更耐性と開発効率を支える、チームの言語設計”**である。
JavaScriptの柔軟性は強力だが、チームやプロジェクトによって書き方がバラけると、
レビュー品質・保守速度・設計の統一感が失われていく。
本稿では、構文・命名・レイアウト・責務の記述指針と、それを守らせる自動化戦略を解説する。
1. スタイルガイド設計の基本5原則
① 可読性：読む人間が最速で理解できるか
② 一貫性：誰が書いても同じ構造になるか
③ 拡張性：変更・追加が破綻しないか
④ 明示性：意図と責務がコードに現れているか
⑤ 自動化：人間判断に依存せず適用できるか
2. 命名規約：構造と責務を反映したルール
✅ 基本形
camelCase → 関数・変数
PascalCase → クラス・React/Vueコンポーネント
UPPER_SNAKE_CASE → 定数
kebab-case → ファイル名（Vue, React, etc）
- ✅ 接頭辞で関数の意図を明示：
get,set,fetch,is,should, etc - ✅ UIコンポーネントは構造名 + 意図：
UserCard,SubmitButton
3. 構文と構造：最小構造で最大の明示性を
// ✅ OK
const getUserName = (user: User): string => user.name;
// ❌ NG: 無意味なラップ
function getName(a) { return a.name; }
- ✅ 短くても意味が明示されているかが重要
- ✅
returnの省略 / ブロックの簡素化など 読みやすさ優先
4. ファイル・ディレクトリ構成ルール
- usecases/ → アプリの振る舞い（動詞ベース）
- components/ → UI部品（名詞ベース）
- stores/ → 状態管理（ドメインごと）
- utils/ → 汎用関数（プレフィックス + 意図）
- types/ → 型定義（ドメイン・用途別に分割）
- ✅ 命名規則と構造がリンクしていると保守がスムーズ
5. コメントと関数責務のガイドライン
// ✅ 意図を説明
// APIレスポンスをドメイン型に変換する
function parseUserResponse(res: ApiUser): User { ... }
// ❌ 処理の繰り返し説明（無意味）
/* 変数aを定義する */ const a = 10;
- ✅ コメントは「何を」より「なぜ」を書く
- ✅ 関数は1責務 → コメント不要なレベルに意味を持たせる
6. 自動化：ESLint / Prettier / husky / CI連携
ESLint（構文 + 構造チェック）
# install
npm install eslint --save-dev
# config
.eslintrc.json
Prettier（フォーマット統一）
npm install prettier --save-dev
.prettierrc
Husky + lint-staged（コミット前に自動適用）
npx husky install
GitHub Actions / CIで強制適用
# .github/workflows/lint.yml
- run: npm run lint
- run: npm run format:check
設計判断フロー
① 誰が読んでも同じように理解できる命名か？
② ファイルとディレクトリ構造が意味に基づいて構成されているか？
③ コメントは意図を伝えているか？ → 処理内容の繰り返しで終わっていないか？
④ 記述の構文が一貫しているか？ → ESLint / Prettierで強制
⑤ 書いたスタイルがコミット・CIレベルで担保されているか？
よくあるミスと対策
❌ プロジェクト内で複数の書き方が混在（function / arrow / class etc）
→ ✅ スタイルガイドで統一し、ESLintで強制
❌ 命名が個人依存で属人化
→ ✅ 命名規則と意味設計をドキュメント化し、レビュー基準にする
❌ レビューで毎回スタイル修正に時間がかかる
→ ✅ Prettier / lint-staged で自動整形 & チェックを事前実行
結語
スタイルガイドとは「美しさ」ではない。
それは**“チームの設計意図を統一し、品質を維持し、設計を可視化するための記述構造”**である。
- 命名に意味と構造を込め
- ファイル構造に意図を反映し
- スタイルと構文を自動で統一し
- コメントと構造で設計を語る
JavaScriptにおけるスタイルガイド設計とは、
“コードベースを言語化し、チーム全体で意図を共有するための文化的戦略”である。