"Packages should not depend on subpackages"

[grimsa]

Context

In "Happy Packaging!" blog post the following packaging rules are proposed:

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.

Example code

See case-1 module.

The main abstraction there is com.company.app.PvModuleLayouts interface which provides access to a somewhat complicated algorithm.
Currently, its implementation is nicely contained in com.company.app.pvmodulelayouts package. So far so good.

Inside the com.company.app.pvmodulelayouts package we have:

• DefaultPvModuleLayouts class - the implementation of the interface which holds the high-level logic of the layout algorithm
• LayoutSpecification interface - an abstraction of algorithm's input parameters
• layoutspecification subpackage - providing two alternative implementations of LayoutSpecification interface

This structure feels right intuitively, and it seems to fulfill the 3 rules with only one exception - object construction.

The challenge

In DefaultPvModuleLayouts there is the following code which seems to break the 1st rule:

LayoutSpecification layoutSpecification = roofFace.slopeAngleInDegrees() < 10
      ? new PvModulesMountedOnRoofFacePlaneLayoutSpecification(pvModuleDefinition)  // from subpackage
      : new PvModulesMountedOnTiltedRacksLayoutSpecification(pvModuleDefinition);   // from subpackage

I don't yet see an acceptable way to reorganize this code to not break the first two rules. The options I considered:

• Pushing the creation logic down into the layoutspecification subpackage by introducing e.g. SlopeDependentLayoutSpecification implements LayoutSpecification (that would delegate to one or the other existing implementation) solves nothing, as then DefaultPvModuleLayouts would still require a dependency on SlopeDependentLayoutSpecification from a subpackage
• Pushing this logic into RoofFace implementation also does not work, as then the 1st rule is still broken (as RoofFace is in the ancestor package)
• Introducing a parallel package tree branch, e.g. com.company.app.objectconstruction
  • Then com.company.app.objectconstruction.SlopeDependentLayoutSpecification depends on the interface and both implementations, but it does not violate the 1st rule as it's in a sibling branch of the package tree
  • Then DefaultPvModuleLayouts depends on SlopeDependentLayoutSpecification which also does not violate the 1st rule (once again - sibling branch of the package tree)
  • However, what was previously a set of classes neatly contained in com.company.app.pvmodulelayouts package (and its subpackages), is now leaking into the new sibling package.
  • It also likely breaks the 2nd rule at the higher level (com.company.app.objectconstruction package introduces new concepts not defined in a higher-level package)

There is also a way to solve this using Spring Framework and dependency injection:

• In com.company.app.pvmodulelayouts create an interface LayoutSpecificationsIndexedBySlopeAngle (for lack of better name) with one method LayoutSpecification find(double slopeAngle). This has no dependency on the subpackage.
• In com.company.app.pvmodulelayouts.layoutspecification define a Spring component that implements the LayoutSpecificationsIndexedBySlopeAngle interface and returns an instance of one or the other implementation depending on given slopeAngle.
• In com.company.app.pvmodulelayouts.DefaultPvModuleLayouts inject an instance of LayoutSpecificationsIndexedBySlopeAngle and then the code becomes LayoutSpecification layoutSpecification = layoutSpecificationsIndexedBySlopeAngle.find(roofFace.slopeAngleInDegrees()); and the 1st rule is no longer broken.

However, relying on Spring Framework feels like a crutch.

Do you see any additional options?

If not, would it be reasonable to add an exception to the 1st rule?

1. Packages should never depend on sub-packages.
    - The only exception is that the constructor of a class located in a sub-package can be called to create an object.

[grimsa]

Here's the summary of the news so far:

• The author of the original blog post kindly shared their experience here
• Two PRs were opened showcasing potential solutions that do not require the exception clause to be added to the 1st rule:
  • [Case 1] Proposed solution #3
  • [Case 1] Solving packaging problem by inverting dependencies #4

I think an important insight is that specific object instantiation (plugging everything together) is not possible with having just one package subtree - it has to be done outside of it (as discussed here).

There's also an example how to implement an ArchUnit test that would enforce this packaging rule (see TNG/ArchUnit#921).