本記事について
当サイトを閲覧いただきありがとうございます。 本記事はシリーズ『生成AI時代のアーキテクチャ超入門』の「アプリケーションアーキテクチャ」カテゴリ第3弾として、命名とコード規約について解説する記事です。
コードを書く時間より「読む時間」のほうが圧倒的に長い。読みやすさはチーム生産性そのものです。本記事では命名の基本原則・Linter/Formatter・ディレクトリ構成・PRレビュー・CODEOWNERS・Gitコミット規約まで、「議論を自動化で終わらせる」規約運用の全体像を示します。
本記事のテーマについてさらに詳しく知りたい方は『アーキテクトの教科書』も参考にしてみてください。
この記事の結論
- 命名・スタイルの議論はLinter / Formatterの自動化で終わらせる
- 規約は機械可読にしてCIで強制する（READMEに書くだけでは守られない）
- 同じ概念には一つの名前。用語辞書はコードを書き始める前に作る
- CODEOWNERSでレビューの責任範囲を明確にする
この記事を読む前に
本記事はプログラムの書き方・整理の仕方の話が中心です。IT用語にあまり馴染みがない方は、基礎編の「プログラムとAPIの基本」を先に読んでおくと格段に分かりやすくなると思います。また、読んでいて分からない用語が出てきたときは用語集で調べながら読み進められます。
そもそも命名規約・コード規約とは何か
命名規約・コード規約とは、ざっくり言えば「チームでコードの書き方を統一するためのルールブック」です。
交通ルールを想像してください。信号の色・車線のルール・標識の意味が統一されているから、初めて走る道でも迷わず運転できます。もしルールが各地域でバラバラなら、すれ違うだけで事故が起きます。コードも同じで、変数名の付け方・インデント・ファイル構成が統一されていれば、誰が書いたコードでも即座に読めます。
なぜ命名とコード規約が重要なのか
もし規約なしでチーム開発したらどうなるか。レビューのたびに「変数名はcamelCaseかsnake_caseか」「インデント」「括弧の位置」といった本質的でない議論が繰り返されます。毎回のPRで30分以上のコメントラリーをしていた現場が、Prettierを導入した翌週にはその手の議論が消えた、という変化は珍しくありません。規約はそれだけで生産性の底上げになります。
命名の基本原則
良い命名の原則は『Clean Code』で整理されています。意図を表す（d ではなく daysUntilExpiration）、嘘をつかない（List<T> という名前で実態が Set<T> はダメ）、発音できる（genymdhms より generationTimestamp）、検索できる（1文字変数はループ変数程度に限定）。この4点を押さえるだけで可読性は一気に変わります。命名はコードに書かれた最大のドキュメントで、命名が良ければコメントはほぼ不要になります。
ケースの使い分けは言語ごとに事実上の標準が決まっています（JS/TS/Javaの変数はcamelCase、クラスはPascalCase、Python/DBはsnake_case、ファイル名はkebab-case、定数はSCREAMING_SNAKE_CASE）。一貫していれば「これは何か」を形から瞬時に判断でき、読む速度そのものが上がります。同一言語内での混在は絶対に避けるのが鉄則です。
対象別の命名パターン
| 対象 | パターン | 例 |
|---|---|---|
| 関数 | 動詞+目的語 | createUser, validateEmail |
| boolean | is / has / canプレフィックス | isActive, hasPermission |
| クラス | 名詞 | OrderService, UserRepository |
| イベント | 過去形 | UserRegistered, OrderPlaced |
| 定数 | 全大文字 | MAX_RETRY_COUNT |
避けたい命名も定番です。
❌ data, info, util ← 何も伝えていない
❌ temp, tmp ← そのまま永続化される罠
❌ mgr, mng, svc ← 過剰な略語
❌ getUserList vs getUsers ← 同義語の混在略語を使う場合はプロジェクト固有の略語辞書（id はOK、usr は禁止、など）を作ってチームで統一します。
筆者メモ ― 「User / Member / Account / Customer問題」
ある大手ECの案件で、同じ顧客情報を扱う機能なのに User / Member / Account / Customer の4つが混在していた、という話が語り草になっています。検索系APIも findUser / getMember / searchAccount の3系統が同じテーブルを叩いていたそうで、新しくジョインしたエンジニアは毎回「今回の要件はどれを直せば正解なのか」を先輩に聞いて回る必要があったとのことです。
原因はシンプルで、Ubiquitous Language（チーム全員が同じ意味で使う共通語彙）が定義されていなかっただけです。規約とは結局、「この辞書を先に作って共有しておく仕事」に他なりません。同じ概念には一つの名前。用語辞書はコードを書き始める前に作ります。
LinterとFormatter ― 議論を強制終了させる道具
Linterは品質問題を検出するツール、Formatterは見た目を自動で整えるツールです。JS/TSならESLint+Prettier（統合型のBiomeが急速に台頭）、PythonならRuff（Black+Flake8+isortを置き換える勢い）、Goはgofmt、RustはClippy+rustfmtが定番です。
現代のフォーマッタは設定可能項目を「意図的に少なく」する哲学で設計されています。「好みで選べる項目が多いと、それが新たな議論の種になる」という経験則で、議論する余地そのものを潰しにいく設計です。ツールの決定は「誰も100%満足しないが、全員が許容できる」レベルで十分です。
そして重要なのは運用方法です。「READMEに書けば守られる」はほぼ幻想で、CIで機械的に強制する段階を踏むのが定石です。
| フェーズ | 導入ツール | 目標時間 |
|---|---|---|
| ① pre-commit | Formatter（Biome / Ruff / gofmt） | 5秒以内 |
| ② pre-push | Lint+型チェック | 30秒以内 |
| ③ PR | 全Lint+テスト+カバレッジ | 10分以内 |
| ④ CODEOWNERS | 重要ファイルの担当レビュー強制 | 自動 |
| ⑤ リリース | semantic-releaseで自動バージョニング | 自動 |
ディレクトリ構成とコメントの原則
ディレクトリ構成は大きく2択です。
[Layer型] [Feature型]
src/ src/
├─ controllers/ ├─ users/
├─ services/ │ ├─ controller.ts
├─ repositories/ │ ├─ service.ts
├─ models/ │ └─ repository.ts
└─ orders/小規模・初心者が多いならLayer型（層の役割が明確）、中〜大規模・多チーム並列開発ならFeature型（機能ごとにコードがまとまる）です。Feature型はモジュラーモノリスやマイクロサービス化の前段階としても機能します。
コメントは「WHY」（なぜ）を書くもので、「WHAT」（何を）を書くものではありません。
❌ // iを1加算する
✅ // 配列末尾にセンチネルを置くので+1する（旧APIの制約）名前で伝わることをコメントに書くと、コードと矛盾した時に嘘になります。「最良のコメントは書かなくて済む命名」です。
PRレビューとCODEOWNERS
PRレビューは品質を守る場であり、チームの学びの場です。原則は、コードに対してコメントし人を批判しない、小さなPR（400行以下、理想は100行）で速いレビューを生む、24時間以内の即応で滞留を防ぐ、「Must / Should / Nit」のラベルでレビュワーの意図を明確にする、の4つです。
決済・インフラ・認証などの重要ファイルは、GitHubの CODEOWNERS で担当チームのレビューを強制します。
# .github/CODEOWNERS
/src/payment/ @payment-team
/infra/ @sre-team
/src/auth/ @security-teamマージ保護ルールと組み合わせれば、知らない人が機密コードを勝手にマージできない状態を作れます。大規模プロジェクトでCODEOWNERSなしは事故の温床です。
コミットメッセージはConventional Commits（feat: fix: docs: refactor: 等のプレフィックス）が事実上の標準です。履歴の検索性が上がり、semantic-releaseで自動バージョニング・チェンジログ生成ができます。
3つのシナリオで考える
個人開発・スタートアップの場合
PrettierとESLintのデフォルト設定に乗るだけで、命名以外の規約論争は消滅してしまいます。命名についてはドメイン用語（ユビキタス言語）のミニ用語集をREADMEに10語だけ書いておく、というのがお勧めです。この最小投資が、半年後の自分への最高の引き継ぎ資料になってくれます。
中小SaaSの場合
規約のCI強制とPR 400行以下、Conventional Commitsを文化として確立する段階です。レビューはMust / Should / Nitのラベルで意図を明確にして、スタイル論争はツールに任せてしまい、人間はロジックに集中するのが理想の形だと思います。
大企業の場合
CODEOWNERSとマージ保護、全社命名規約が必須装備になります。決済・インフラ・認証などの重要なファイルは担当チームのレビューを強制して、知らない人が機密コードを勝手にマージできない状態を作っておきます。用語集はドメインごとに整備しておくと、新人教育の教材まで兼ねてくれるので一石二鳥です。
AI判断軸 ― 規約のCI強制がAIの品質ゲートになる
命名規約がAI生成コードの一貫性を保つ
プロジェクトの命名規約がLinterで強制されていれば、AIが書いたコードもCIで自動修正されます。AIは学習データの多数派に引きずられて、プロジェクト固有の規約と異なる命名を書くことがありますが、Linterが即座に検出するため問題になりません。逆に規約が口頭・README止まりだと、AI生成コードのスタイルばらつきがレビュー負荷として跳ね返ります。
スタイル議論を人間から完全に排除する
Prettier・ESLint・RuffをCIで強制する仕組みがあれば、AI生成コードも人間のコードも同一スタイルに統一されます。スタイルの議論を人間の判断から完全に排除できるため、レビューは設計とロジックに集中できます。AIがコードの大半を書く時代には、この「機械的な品質ゲート」の価値がさらに上がっています。
やってはいけないこと
チーム全体の生産性を削る地雷を、特に危険な6つに絞ります。
| 禁じ手 | なぜダメか → どうするか |
|---|---|
| 同じ概念を複数の名前で扱う | 新人が毎回「どれが正解か」を聞き回る事態になる → 用語辞書を先に作る |
data / info / temp などの曖昧語 | 意図ゼロで temp が本番に永続化される → 意図を表す具体名を付ける |
| Linter警告を「後でまとめて直す」 | 100個を超えた時点で誰も見なくなる → 警告ゼロを維持する |
| コミットメッセージを自由形式で書く | 履歴検索・チェンジログ生成が効かない → Conventional Commitsにする |
| CODEOWNERSなしで決済・認証をマージ可能にする | 知らない人が機密コードを変更できる → 重要パスに設定する |
| PRの粒度が1000行超 | レビューが形骸化する → 400行以下、理想は100行に分割する |
規約は議論するものではなく、ツールに任せるものです。「タブかスペースか」の議論は技術的に終わっています。
決めるべきこと — 自分のプロジェクトでの答えは？
以下の項目について、自分のプロジェクトの答えを1〜2文で言語化してみてください。曖昧なまま着手すると、必ず後から「なぜそう決めたんだっけ」が問われます。
- 命名規則（ケース・プレフィックス・禁止用語・用語辞書）
- Linter / Formatterの選定とCI強制の段階
- ディレクトリ構成（Layer型 / Feature型）
- PRサイズの目安・レビューSLA
- CODEOWNERSの運用
- Gitコミットメッセージ規約（Conventional Commits等）
この記事に関連する記事
まとめ
本記事は命名とコード規約について、命名原則・Linter/Formatter・PRレビュー・CODEOWNERS・Conventional Commitsまで含めて解説しました。如何だったでしょうか。
議論を自動化で終わらせ、規約を機械可読にする。これがAI時代も含めた2026年のコード規約運用の現実解です。
次回はアプリケーションアーキテクチャカテゴリの最終記事、エラーハンドリング（Result型・Circuit Breaker・冪等性）について解説します。
シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方
本記事で扱った内容の詳細は Google Style Guides も合わせて参考にしてください。
それでは次の記事も閲覧いただけると幸いです。
📚 シリーズ：生成AI時代のアーキテクチャ超入門（34/95）