"Sub-packages should not introduce new concepts, just more details"

[grimsa]

Let's say we're building a new app and we'd like to follow these packaging rules:

1. Packages should never depend on sub-packages.
2. Sub-packages should not introduce new concepts, just more details.
3. Packages should reflect business-concepts, not technical ones.

We start with the following packages:

• com.company.domain (for the domain model)
• com.company.app (for Main class and app configuration that ties everything together)

An implication of the "Packages should never depdend on subpackages" rule is that having two high-level packages is inevitable (because we need to instantiate/plug-together the domain model objects, and having that code anywhere in the same package subtree that holds the domain objects would break the rule).

Now let's assume the domain of the app is that of managing various types of reference data, where different types of reference data have few or no dependencies at all. Let's say the types of reference data are:

• Airports
• Plane models
• Weather data

In such case it would seem natural to organize the domain model into 3 subpackages - one for each type of reference data:

• com.company.domain.airport
• com.company.domain.plane
• com.company.domain.weather_data

It could be argued that the subpackages of com.company.domain break the "Sub-packages should not introduce new concepts, just more details" rule, as:

• com.company.domain package has no classes inside of it (i.e. it defines no highest-level concepts)
• yet com.company.domain.* subpackages introduce new concepts, rather than refining higher-level ones

However, it seems that using subpackages solely for logical grouping has value, and could be useful at different levels of the package hierarchy.

In addition to the example above, the com.company subpackages (domain and app) are also there just for the logical grouping they provide.

But subpackages for logical grouping can be useful at a lower level as well.

Let's consider another example. Let's say we're modeling local codes defining the requirements for electrical installations (here NEC stands for "National Electrical Code" and CEC stands for "California Electrical Code"; every few years a new version of code comes out that changes some requirements). The following structure would seem to be in line with the 3 packaging rules:

package com.company.domain
	- interface ElectricalCode (a common interface)
	- subpackage nec2020
		- class Nec2020 implements ElectricalCode
		- supporting classes
	- subpackage nec2017
		- class Nec2017 implements ElectricalCode
		- supporting classes
	- `subpackage cec2019`
		- class Cec2019 implements ElectricalCode
		- supporting classes

Yet if we also have other concepts in com.company.domain package, implementation of which is placed in related subpackages, then our electrical code implementation subpackages might get lost among implementations of other concepts. A simple solution is to use electrical_code subpackage for logical grouping of nec2020, nec2017, and cec2019 subpackages.

package com.company.domain
	- interface ElectricalCode (a common interface)
	- subpackage electrical_code
		- subpackage nec2020
			- class Nec2020 implements ElectricalCode
			- supporting classes
		- subpackage nec2017
			- class Nec2017 implements ElectricalCode
			- supporting classes
		- subpackage cec2019
			- class Cec2019 implements ElectricalCode
			- supporting classes

This feels like an improvement with seemingly no downsides.

Similarly, if over the years more editions of NEC and CEC codes were added, we may want to group them together into nec and cec subpackages as well:

package com.company.domain
	- interface ElectricalCode (a common interface)
	- subpackage electrical_code
		- subpackage nec
			- subpackage _2020
				- class Nec2020 implements ElectricalCode
				- supporting classes
			- subpackage _2017
				- class Nec2017 implements ElectricalCode
				- supporting classes
		- subpackage cec
			- subpackage _2019
				- class Cec2019 implements ElectricalCode
				- supporting classes

This would also seem like an improvement, assuming there were e.g. 3+ versions of each type of electrical code to warrant the grouping.

This suggests we can use one or multiple levels of subpackages to express just the logical grouping at any level of the hierarchy.

At first I thought that the consequence of this was that if we are considering package P and its subpackages, we can have only two distinct cases (with no overlap):

• Either P defines some concepts (i.e. has some classes or interfaces), and subpackages provide implementations/additional details at a lower-level of abstraction,
• Or P is empty and only provides logical grouping for the contained subpackages

However, this is not the case.
If we modify the example above by adding SomeNecCalculationCommonToAllEditions class that would be used by both Nec2020 and Nec2017, then com.company.domain.electrical_code package would both serve as logical grouping for different NEC versions, AND also introduce a new higher-level concept of some calculation common to all versions of NEC:

package com.company.domain
	- interface ElectricalCode (a common interface)
	- subpackage electrical_code
		- subpackage nec
			- class SomeNecCalculationCommonToAllEditions
			- subpackage _2020
				- class Nec2020 implements ElectricalCode
				- supporting classes
			- subpackage _2017
				- class Nec2017 implements ElectricalCode
				- supporting classes
		- subpackage cec
			- subpackage _2019
				- class Cec2019 implements ElectricalCode
				- supporting classes

So the conclusions would seem to be that:

• Using subpackages for logical grouping seems to:
  • Be useful
  • Have no significant downsides
  • Be aligned with the purpose behind the 3 packaging rules - to produce a reading-optimized package hierarchy where more abstract things are higher up in the hierarchy
• Therefore, it seems there should be some interpretation of "Sub-packages should not introduce new concepts, just more details" that allows for using subpackages for logical grouping at any level of the hierarchy
• The distance in the package hierarchy between the abstraction and its implementation/details can be greater than 1 (as seen in example of com.company.domain.ElectricalCode and com.company.electrical_code.nec._2020.Nec2020). In other words, implementation does not have to reside in first-level subpackage, it can be placed at a deeper level if needed.

[grimsa]

In such case it would seem natural to organize the domain model into 3 subpackages - one for each type of reference data:

• com.company.domain.airport
• com.company.domain.plane
• com.company.domain.weather_data

One consequence of this I noticed is that there is a chance of having the same name appear twice in the package tree, which feels awkward.
For example:

── com.company.domain
   ├── airport
   │   ├── Airport.java (interface)
   │   ├── Location.java (interface)
   │   ├── ... (other interfaces/top-level classes)
   │   ├── airport
   │   │   ├── JsonAirport.java (class, implements Airport)
   │   │   └── ... (other supporting classes)
   │   └── location
   │       ├── JsonLocation.java (class, implements Location)
   │       └── ... (other supporting classes)
   ├── plane
   │   ├── ...
   │   └── ...
   └── weather_data
       ├── ...
       └── ...

Notice we have com.company.domain.airport package for logical grouping of everything related to "airport" subdomain/domain slice/logical grouping, but then we also have com.company.domain.airport.airport for implementation details of an Airport concept within the "airport" subdomain.

One way to work around this could be to update the domain subpackage name to indicate it's a subdomain, e.g.:

• com.company.domain.airports_subdomain.airport.JsonAirport
• com.company.subdomain_airports.airport.JsonAirport
• com.company.subdomain_airports.airport.JsonAirport

Using plural for naming domain slices (i.e. com.company.domain.airports.airport.JsonAirport) would probably not work, as not all domain slices may have both singular and plural names (e.g. weather_data).

[vzurauskas]

I think this is a good illustration of when using packages for grouping can be useful. Anyway, I have a couple of points I want to make.

I don't think your example violates the second rule, at least the way I interpret it. I see architecture as fractal - what is detail at a higher level can become a concept at a lower level. In domain package (I actually would not bother with domain package and just begin at root) you start with ElectricalCode interface - a single concept. Subpackages introduce new details of the ElectricalCode concept, namely that it can be either nec or cec. What is important is that they don't introduce any new concepts of the same level as ElectricalCode. Moving one level below, nec and cec become concepts, and further subpackages introduce new details for them, namely the specific yearly specifications. Again, what is important is that if there is a Texas Electrical Code tec, it's not introduced here, but at the level above.

Another point I want to make is that I don't think the readability of the package hierarchy is the only, or even the most important purpose of the three rules. I think another purpose is to maximize cohesion and minimize coupling between packages, making large scale refactoring, or even decomposing the codebase easier.

Finally, just to nitpick, two high level packages, where one depends on the other to plug together the domain model objects, is not srictly inevitable. I wouldn't recommend this, but technically you could move out all top level domain packages into separate libs, import them as compile time dependencies and make the whole application just the app package.