Best practice for api vs implementation in multi-module project

What you describe is a fairly common discussion about layered architecture systems, also known as “strict” vs “loose” layering, or “open” vs “closed” layers. See this (hopefully free for you too) chapter from Software Architecture Patterns for some semiotics which is unlikely to help you much with your choice

From my point of view, if a module needs to break layering, I’d model the project structure to expose this in the most direct and visible way. In this case it means adding library as implementation dependency of feature1. Yes it makes the diagram uglier, yes it forces you to touch few more files on upgrade, and that is the point - your design has a flaw and it is now visible.

If few modules need to break the layer encapsulation in the same way, I may consider adding a separate base module exposing that functionality, with a name such as base-xyz. Adding a new module is a big thing, not because of the technical work, but because our brain can handle only so many “things” at a time (chunking). I believe the same would hold for Gradle “variants” when they become available, but I can’t claim that yet as I haven’t tried them hands on.

If all clients of the base module need to access library (i.e. because you use classes or exceptions from library in your public signatures) then you should expose library as API dependency of base. The downside of that is that library becomes part of the public API of base, and it is probably bigger than you would like, and not under your control. Public API is something you are responsible for, and you want to keep it small, documented, and backwards compatible.

At this point you may be thinking about jigsaw modules (good), osgi (err… don’t), or wrapping the parts of lib that you need to expose in your own classes (maybe?)

Wrapping only for the sake of breaking dependencies is not always a great idea. For one it increases the amount of code you maintain and (hopefully) document. If you start doing small adaptations in the base layer, and the library is a well known library, you introduce (value added) inconsistencies - one needs to always be on guard whether their assumptions for lib still hold. Finally, often the thin wrappers end up leaking the library design, so even if they wrap the API - that still forces you to touch the client code when you replace/upgrade lib, at which point you may have been better off using lib directly.

So, as you can see, is about trade-offs and usability. The CPU doesn’t care where your module boundaries lie, and all developers are different - some cope better with large amount of simple things, some cope better with small number of highly abstract concepts.

Don’t obsess about the best (as in What Would Uncle Bob Do) design when any good design would work. The amount of extra complexity that is justified for the sake of introducing order is a fuzzy quantity, and is something that you are in charge of deciding. Make you best call and don’t be afraid to change it tomorrow :slight_smile:

2 Likes