Best practice for api vs implementation in multi-module project


(Robert) #1

Reposting SO question here as it looks like a better place for advance topics

Let say I have the following modules in an application

  • library
  • base
  • feature1
  • feature2
  • app

Now the relations between the modules are:

base wraps library

feature1 and feature2 make use (depends) on base

app puts together feature1 and feature2

Everything in this multi module structure should be able to work using Gradle’s implementation dependencies and there’s no need to use the api clause anywhere.

Now, let say feature1 needs to access an implementation detail of base included in library .

In order to make library available to feature1 we have two options as far as I can tell:

  1. Change implementation for api in base to leak the dependency to modules that depend on base
  2. Add library as an implementation dependency to feature1 without having base leak the dependency on library

Of course the example has been simplified for the sake of the question, but you understand how this can became a configuration hell with a big number of modules with 4 or 5 levels of dependencies.

We could create a base-feature intermediate module that can wrap base and provide another level of abstraction for feature1 to consume without leaking library , but let’s leave that solution out of the scope of this problem to focus on the setup of the dependencies.

Some trade-offs that I detected on the above options:

Option 1) pros

  • Smaller build.gradle 's files, as no need to repeat implementation clauses
  • Faster build scrips edits. Just make the single change on the api clause and see the changes propagated to all consumer modules

Option 1) cons

  • Classes might come up available in modules that shouldn’t have access to them.
  • Prone to miss use by developers, as they have implementations available and not only the module interfaces.

Option 2) pros

  • It makes crystal clear which dependencies the module has.
  • No guessing where the classes are coming from (think 4 or 5 levels of modules leaking dependencies), as their origin is always declared in the module dependencies.

Option 2) cons

  • Makes updating a dependency more tedious, as all the modules with the implementation clause have to be modified. Even though I believe this is a good thing because it keeps track exactly of how a change modified the project, I see how it can take more time.

Now the questions :

  • Is there any trade-offs in terms of compilation of this multi-module scenario?
  • Is a module leaking a dependency “faster” to be compiled for consumer modules?
  • Does it make a substantial difference in build times?
  • What other side effects, pros/cons am I missing ?

Thanks for your time.


(Dimitar Dimitrov) #2

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:


(Robert) #3

@ddimitrov thank you for a very detailed answer and the link to the chapter (it was indeed for free to me as well)

I was aware that, at this point, it’s a matter of personal preference as I don’t see a clear “best” option. However I was curious to read other points of views and arguments for/against each of the approaches.

I would agree with you. I believe that being expressive and declaring every dependency in the setup, makes it easier to understand and read, while slightly slower to change and/or update.

3rd party libs are indeed tricky.

My concern about build performance was based on the fact that this is an Android project with ~60 modules and up to 5 layers. Most of the modules are Android libraries with resources that need to be processed, kotlin code, etc. that take a while to build. If there was any considerable save in terms of build times, then I would definitely consider it as part of the decision, as the developer experience improves with faster builds.

Thank you again for your answer and let me know if you would be interested in posting it in SO as an answer, or you are OK with me doing so.


(Dimitar Dimitrov) #4

Done, with some editing.