読みやすいコードは、短いコードやコメントの多いコードと同じではありません。
画面表示、業務ルール、データ取得、外部サービスの責任が分かれ、変更理由ごとに修正場所を予測できるコードです。
最初から層を増やしすぎず、同じ判断が二か所へ現れた時点で共通の責任へ移してください。
アプリ開発の目的に合う相談先は、外注と学習を目的別に分けた相談ガイドにまとめています。
| 責任 | 主な内容 | 変更理由 |
|---|---|---|
| 表示 | 画面、入力、状態表示 | UIや操作の変更 |
| アプリ処理 | 操作の順序、権限、状態遷移 | ユースケースの変更 |
| 業務ルール | 計算、制約、判定 | 業務方針の変更 |
| データ、外部 | API、DB、端末機能 | 接続先や保存方法の変更 |
四つの責任を依存方向で分ける
画面から直接DBや外部APIを呼ぶと、表示変更と通信変更が同じファイルへ集まります。
画面は利用者操作をアプリ処理へ渡し、アプリ処理は業務ルールを実行し、データ層の抽象を通じて外部へ接続します。
| 層 | 知ってよいもの | 直接知りすぎないもの |
|---|---|---|
| 表示 | 画面状態と操作 | DBの表構造、APIの秘密値 |
| アプリ処理 | ユースケースと権限 | UI部品の細部 |
| 業務ルール | 値と規則 | フレームワーク、通信 |
| データ、外部 | API、DB、端末SDK | 画面の見た目 |
層の数は目的ではありません。
小さなアプリで一操作しかないなら、明確な関数とファイルで十分な場合もあります。
一方向の依存にすると、業務ルールを画面や通信なしでテストしやすくなるでしょう。
外部APIを差し替える場合も、アプリ処理の入出力を保てれば影響範囲を狭められます。
機能単位のフォルダーへ共通責任を組み合わせる
screens、models、servicesのようなファイル種類だけで分けると、一機能の変更が遠い場所へ散らばることがあります。
予約、会員、通知など機能単位のまとまりを作り、その中で表示、処理、データを分ける方法があります。
次の手順で構成を決めてください。
- 利用者の主要機能を名詞ではなく行動で並べる
- 各機能の表示、処理、業務ルール、データ接続を洗い出す
- 複数機能で本当に同じ規則だけを共通へ移す
- 外部SDKを薄い接続層で包み、利用箇所を限定する
- 公開APIと内部実装の境界をテストで固定する
- 新しい変更で迷ったファイルを設計見直しの記録にする
「共通」という名前のフォルダーへ何でも置くと、どこからでも参照される巨大な依存になります。
共通化する条件は、コードが似ていることより同じ理由で変更されることです。
安全な開発環境と成果物を守る観点は、NIST Secure Software Development Frameworkでも開発工程の活動として扱われています。
秘密値、署名鍵、生成物、依存関係をソースコードと同じフォルダー規則だけで管理しないでください。
六画面の重複判定を一か所へ移す計算例
次の数字は、重複した業務ルールの変更負担を示す仮定です。
会員の利用可否判定を6画面へそれぞれ書き、規則が年4回変わるとします。
各回で6か所を直すなら、年間の修正候補は6画面×4回で24か所です。
判定を一つの業務ルールへ集約し、6画面が結果を使う形なら、規則本体の年間修正は4か所です。
| 方法 | 1回の規則変更 | 年4回 |
|---|---|---|
| 六画面へ重複 | 6か所 | 24か所 |
| 一つの規則へ集約 | 1か所 | 4か所 |
| 差 | 5か所 | 20か所 |
共通化後も各画面の表示テストは必要です。
削減できるのは業務規則の定義箇所であり、影響確認がゼロになるわけではありません。
ビルドをソースコードから配布物へ変換する工程として管理する
ビルドは、ソースコードをコンパイルする一操作だけを指しません。
依存関係の取得、コード生成、資産の変換、環境設定、署名、パッケージ化、テストを組み合わせて配布物を作ります。
ローカルで成功しても、誰のPCでも同じ成果物を作れなければ保守できません。
言語、SDK、ビルドツール、依存関係の版を固定し、開発、検証、本番の設定項目を分けます。
公開版の番号規則を決める際は、Semantic Versioningのように、互換性を壊す変更、互換性のある機能追加、修正を番号へ対応させる考え方を参考にできます。
採用する場合は、アプリ内部のAPIとストア表示版のどこへ適用するかを明記してください。
ビルド出力には、ソースの版、依存関係、実行日時、対象環境を記録します。
障害時にどのコードから作られた配布物かを追えることが重要です。
小さな差分をレビューして主ブランチを保つ
大きな機能を一度に提出すると、業務ルール、UI、DB変更、設定変更が混ざり、失敗原因を追いにくくなります。
一つの判断または利用者価値ごとに差分を小さくし、確認方法を添えてください。
GitHubのPull Requestレビュー資料は、コメント、承認、変更要求を差分へ関連付ける仕組みを説明しています。
レビューでは命名だけでなく、責任の置き場所、依存方向、テスト、移行手順を確認します。
主ブランチの保護には、GitHubの保護ブランチ資料を参考に、承認や状態チェックをマージ条件に設定できます。
緊急修正で例外を使った場合も、後からレビューとテストを補完する記録を残してください。
VS Codeを使うチームなら、ソース管理クイックスタートで、差分確認、ステージ、コミットの基本操作をそろえられます。
アプリのコード設計でよくある質問
フォルダーは機能別とファイル種類別のどちらがよいですか？
一機能の変更がどこへ届くかを追いやすい方を選びます。
機能単位を基本にし、複数機能で同じ理由により変わる業務規則や接続処理だけを共通へ移す方法が一つの選択肢です。
コメントを増やせば読みやすくなりますか？
判断理由、外部制約、意図的な例外には役立ちますが、コードと同じ内容の説明は更新時にずれます。
名前、責任分離、テストで表せる内容はコードへ置き、背景と「なぜ」をコメントに残します。
バージョン番号はどのように付けますか？
互換性を基準にするなら、Semantic Versioningの公式仕様を参照できます。
ストア版、内部API、DB移行へ同じ番号を無条件で使わず、対象と互換性の定義をチームで決めてください。
変更理由が一か所へ届くコード設計を保つ
保守性は、将来の変更内容を正確に予測することではなく、変更が届く責任と確認方法を狭く保つことです。
重複を見つけた時点で共通化し、外部依存を境界へ寄せ、小さな差分で設計を更新します。
- 表示、アプリ処理、業務ルール、データ、外部で異なる変更理由
- 共通化の条件は似たコードではなく同じ理由による変更
- 再現可能なビルドに必要なSDK、依存関係、設定、署名、成果物情報
- 小さな差分で確認する責任、依存方向、テスト、移行手順
コードの変更単位が見えたら、アプリ開発スケジュールの工程と管理方法で設計、実装、レビュー、試験を依存関係のあるタスクへ変換できます。
