【ITニュース解説】Package naming nobody cares about (but should)

パッケージの命名と整理は、保守しやすいコードを書く上で非常に大切なことである。ファイルをどのようにグループ化し、モジュールを配置するかは、コードの読みやすさだけでなく、コードのナビゲーションや今後の開発のしやすさにも大きく影響する。

プログラミング初心者にとって、「Hello World」プログラムの次に学ぶ概念の一つが「パッケージ」だろう。JavaやKotlinといった言語で、パッケージはコードを整理するためのフォルダ構造であり、名前の衝突を防ぐものだと単純に説明されることがある。この説明は部分的には正しいが、パッケージをいつ、どのように使うべきかについて誤った理解を生む可能性がある。より正確には、パッケージとは、関連するクラス、インターフェース、列挙型などの「型」をまとめるための「名前空間」のことである。これは、大規模なアプリケーションや外部ライブラリを統合する際に、同じ名前のクラスが複数存在しても区別できるようにするための仕組みである。

しかし、JavaやKotlinにおけるパッケージの実現方法、そして統合開発環境（IDE）の扱い方により、パッケージは理想的な「名前空間」として完全に機能しないという側面もある。その結果、開発者はパッケージ名に頼らず、クラス自体に十分な情報を込めた名前を付けがちになる。例えば、「UserAnalyticsReport」や「OrderRepository」といったクラス名がそうだ。これらのクラスが「com.example.user.UserAnalyticsReport」のような論理的なパッケージに配置されていても、ほとんどの開発者はIDEの自動インポート機能を使うため、パッケージ構造について深く考える機会が少ない。

このような状況は、「パッケージは単なるフォルダであり、ファイルをグループ化する場所である」という誤った考え方につながることがある。その結果、コードが目的ではなく物理的な場所によって整理され、それぞれのクラスやパッケージの責任が不明確になる。これは一見整理されているように見えても、実際には多くの問題を引き起こす悪い設計モデルである。

より良い考え方は、パッケージを「意味的な境界」として捉えることである。パッケージは、そのコードがシステムのどの部分に属し、どのような責任を負っているのかを示すものである。パッケージを本当の意味での名前空間として扱うことで、いくつかのメリットが生まれる。まず、パッケージ名自体がコードのドキュメントの一部となり、クラスがどこにあるかを見るだけで、その役割や責任をある程度推測できるようになる。次に、関連する機能は自然に同じ場所に集まり、無関係なコードは離れて配置されるようになる。これにより、「このクラスや関数は何を担当しているのか？」という問いに対して明確な答えが得られやすくなる。

特に問題になりやすいのが、「model」「dto」「entity」「utils」「common」「core」といった汎用的なパッケージ名の乱用である。例えば、ユーザー関連の機能を開発する複数のチームがいる大規模なプロジェクトで、「com.example.user.model.profile」や「com.example.user.utils.profile」のように、同じ「profile」という概念が複数のパッケージに散らばってしまうことがある。これは、単に「user」パッケージ内のファイル数を減らしたいという理由で「profile」を独立したパッケージにしてしまったり、チームによって命名規則が異なったりすることで発生する。結果として、どこに何があるのか分かりにくくなり、新しいメンバーのオンボーディングが困難になったり、用語の不統一が生じたりする。このような汎用的なパッケージ名は、コードの責任を明確にするのではなく、曖昧な分類ラベルとして機能してしまうため、コードベースの理解を難しくする。

では、どのようなものが独立した名前空間、つまり独立したパッケージに値するのだろうか。汎用的なmodelやutilパッケージを作成すべきでないことは比較的理解しやすいが、実際に何が独立したパッケージとなるべきかの判断は難しい。例えば、「com.example.user」パッケージ内に「settings」や「profile」、「security」といったサブパッケージがある場合を考える。ここで重要なのは、これらのサブパッケージが「ユーザーの概念なしに意味を成すか？」、「このパッケージ内の要素がユーザーパッケージの外で独立して使われることがあるか？」、「このパッケージが独自のAPIを持つ独立したまとまりとして機能するか？」といった問いに答えることである。もしこれらの問いのいずれかに「はい」と答えられるなら、それは独立したパッケージとして存在価値があるかもしれない。しかし、もしすべて「いいえ」であれば、それらはuserパッケージ内に統合されるべきである。

また、「.common」や「.core」といったパッケージも避けるべきだ。これらのパッケージは「他にどこにも当てはまらないもの」を置く場所になりがちで、特定のまとまりや明確な境界を表さない。時間が経つにつれて、無関係なコードが次々と放り込まれ、システム全体の多くの部分から依存される「巨大なパッケージ」と化してしまう。これにより、コードの結合度が高まり、リファクタリングが危険で困難になるという建築上の劣化を引き起こす。

ドメイン駆動設計（DDD）における「集約（Aggregate）」という考え方は、名前空間を設計する上で有効なヒントになる。パッケージは、外部から見て意味と有用性を持つまとまった概念を表すべきだという考え方である。例えば、値オブジェクト、ドメインエンティティ、イベントなどは、単独では意味を持たず、集約をサポートするために存在するものであるため、通常は独立したパッケージにするべきではない。これらは集約と同じパッケージにまとめることで、それらの要素がその集約のコンテキストにおいてのみ意味を持つことを示し、システム構造を不明瞭にする人工的な境界の作成を避けることができる。

これまではドメイン内部でのパッケージ化、つまり「ミクロレベル」での話をしてきたが、ドメイン、インフラストラクチャ、プレゼンテーションといった「マクロレベル」のアーキテクチャレイヤーもパッケージとして扱うことができる。これらのパッケージは、アーキテクチャ上の境界を示し、システム全体の大まかな構造を開発者に伝える。各レイヤーはそれぞれがまとまりのある単位として機能するため、これらは意味のない技術的なラベルではなく、明確な境界として機能する。

パッケージに名前を付ける際も、そのパッケージが表す「概念」に基づいて命名するべきであり、中に含まれるファイルの「数」に基づいて命名してはならない。例えば、単一の「Order」という概念を扱うパッケージであれば、「orders」ではなく「order」と名付けるべきである。「orders」という複数形はコレクションを示唆してしまうため、概念自体を表す単数形がより適切である。例外として、newsのように概念自体が複数形である場合はその限りではないが、ほとんどの場合、単数形を使うのがデフォルトである。

パッケージ構造の優先順位も重要である。「com.example.domain.user」のように技術レイヤーを最初に置く構造と、「com.example.user.domain」のようにビジネス上の概念を最初に置く構造では、コミュニケーションされる優先順位が大きく異なる。後者の「概念ファースト」のアプローチは、システムが成長しても、常にビジネス上の関心事からアプローチできるため、ナビゲーションが容易で、柔軟性が高まる。概念が最優先であり、その概念がどのように実装されているか（ドメイン層なのか、インフラ層なのか）は二の次であるという考え方が大切である。

まとめると、パッケージを作成する際には、「デフォルトでは作成せず、明確な理由がある場合にのみ作成する」という原則を持つべきである。独立した分離が必要な場合、例えばレイヤー化されたアーキテクチャを構築する際や、パッケージ自体が独立した意味を持つ凝集された単位である場合にのみ、個別のパッケージに分けることが正当化される。utils、extensions、helpers、implといった汎用的なパッケージは作成すべきではない。また、概念を最優先し、その後に技術レイヤーを続く形にし、パッケージ名はデフォルトで単数形を使うのが良い。

これらの考え方は、JavaやKotlinだけでなく、TypeScriptのモジュールシステムなど、名前空間の概念を持つ他の言語にも適用できる。ディレクトリ内に5つ以上のファイルがあっても、それは決して恐れることではないのだ。