Using Third-Party Code
There is a natural tension between the provider of an interface and the user of an interface.Providers of third-party packages and frameworks strive for broad applicability so they can work in many environments and appeal to a wide audience,Users, on the other hand, want an interface that is focused on their particular needs.This tension can cause problems at the boundaries of our systems.
We are not suggesting that every use of Map be encapsulated in this form.Rather, we are advising you not to pass Maps arround your system.If you use a boundary interface like Map, keep it inside the class, or close family of classes, where it is used.Avoid returning it from, or accepting it as an argument to, public APIs.
Exploring and Learning Boundaries
Third-party code helps us get more functionality delivered in less time.Where do we start when we want to utilize some third-party package? It's not our job to test the third-party code,but it may be in our best interest to write tests for the third-party code we use.
Instead of experimenting and trying out the new stuff in our production code, we could write some tests to explore our understanding of the third-party code.In learning tests we call the third-party API, as we expect to use it in our application.We're essentially doing controlled experiments that check our understanding of that APT.The tests focus on what we want out of the API.
Learning log4j
We want to use the apache log4j package rather than out own custom-built logger.We can encapsulate that knowlegde into our logger class so that the rest of our application is located from the log4j boundary interface.
Learning Tests are Better Than Free
The learning tests end up costing nothing.We had to learn the API anyway, and writing those tests was an easy and isolated way to get that knowledge.The learning tests were precise experiments that helped increase our understanding.
Not only are learning tests free, they have a positive return on investment.When there are new releases of the third-party package, we run the learning tests to see whether there are behavioral differences.
Learning tests verify that the third-party packages we are using work the way we expect them to.Once integrated, there are no gurantees that the third-party code will stay compatible with our needs.The original authors will have pressures to change their code to meet new needs of their own.They will fix bugs and add new capabilities.With each release comes new risk.If the third-party package changes in some way incompatible with our tests,we will find out right way.
Whether you need the learning provided by the learning tests or not, a clean boundary should be supported by a set of outbound tests that exercise the interface the same way the production code does.Without thest boundary tests to ease the migration, we might be tempted to stay with the old version longer than we should.
Using Code That Does Not Yet Exist
There is another kind of boundary,one that separates the known from the unknown.There are often places in the code where our knowledge seems to drop off the edge.Sometimes what is on the other side of the boundary is unknowable.Sometimes we choose to look no farther than then boundary.
Clean Boundaries
Interesting things happen at boundaries.Change is one of those things.Good software designs accommodate change without huge investments and rework.We use code that is out of our control, special care must be taken to protect our investment and make sure future change is not too costly.
Code at the boundaries needs clear separation and tests that define expectations.We should avoid letting too much of our code know about the third-party particulars.It's better to depend on something you control than on something you don't control,lest it end up controlling you.
We manage third-party boundaries by having very few places in the code that refer to them.We may wrap them as we did with Map, or we may use an ADAPTER to convert from our perfect interface to the provided interface.Either way our code speaks to us better, promotes internally consistent usage across the boundary, and has fewer maintenance point when the third-party code changes.