Information hiding for services

Clean Code
1

Background
I’m working as a QE Automation Engineer for a retailer on a mobile app. We use cucumber/rspec for automating tests. The “framework team” designs and maintains the basic structure that we use for building and running our tests. Our QE team builds our own classes to access the various services that we use to get data from the retailer’s backend. For example, getting promotion data, signing on/off the site, adding/updating the shopping cart, etc.

A new group recently started managing the framework and mandated a change which I believe is fundamentally flawed and I’d like to know if I’m off-base or not. Here’s the deal.

Old Structure
We used to maintain our service classes in a single directory, something like
Clients/Promotions or Clients/Cart
If the backend changed, we would restructure the class to take the changes into account. We would do this even if the backend service itself changed, such as being replaced by a new service providing equivalent data.

New Structure
Now we are required to move our service modules to a new location (and thus redefine the calling signature) if the backend service changes. So if we go from service ‘AAA’ to service ‘BBB’, we now have to move
Clients/Promotions
to
Clients/BBB/Function/V1/Promotions
to recognize the new service as well as the version that this service is currently on!

Note that these new services are often internal to the retailer – not outside services. They are simply upgrading their capability and offering new features… constantly.

Tradeoffs
The framework guy says things like:

  1. This new structure is easier for newbies to use
  2. If they change the basic service then we should change our QE interface
  3. We can only protect against breaking changes at the minor level, not the major level

I say that this new structure guarantees we will have to accept breaking changes under almost every conceivable change in the backend. And newbies should first use the service and then – if there’s a problem – go digging for more information. And what about documentation (e.g., Yardoc) which we should but don’t have…

In my mind, this way lies madness. I’ve already seen three major version changes in one service (in 16 months) and now that service is going away and being replaced by other services. And this discussion is only about the basic API structure, we haven’t scratched the surface regarding “true” data hiding by wrapping the calls and returning s “standard” data structure where ever possible.

Am I just not understanding this issue?

2

Yikes!

There’s a word for this: coupling. It sounds like this change would introduce a heck of a lot of it. Generally, this is something to minimize.

I’d be arguing against this change too.

(I documented a few types of coupling here, maybe useful? Types of Coupling)

3

Nice, article on coupling, Ben… thanks. I haven’t decided what to call this one: “Pathological” is certainly good, but I think “Content Coupling” is the appropriate designation. There’s a nice image here.

One of the classics on coupling and modular design is “Reliable Software Through Composite Design” by Glenford J. Myers. It’s one of the earliest books that I have which discusses the topic in some detail.

I’ve pushed this up the line and it looks like we’ll at least have a meeting the group managing the infrastructure.

4

So now I know where this approach came from: this RailsCast article: #350 REST API Versioning - RailsCasts. “See; Rails does it!.”

They seem to have forgotten that in spite of that, the calls are still Product.find, Product.destroy, etc. Sheesh