Stick with mis-named concepts or rename them in wrapper code?

Question

I'm writing a library which includes some wrapper code for some underlying API. In that underlying API, there are two concepts, "foo" and "bar", whose literal meaning in the English dictionary is close to the switching of their meaning in the API. i.e. it uses "foo" for something that's close to "bar" and vice-versa.

(For the curious: It's basically "thread index" vs "thread id" in CUDA. Which one do you suppose is 3-dimensional and which is a linearization of the other?)

Now, in my wrapper code, should I...

• Stick with their incorrect and confusing terminology?
• Switch it back, explaining profusely in comments when I'm doing that?
• Go for other terms, which won't get people mixed-up, but introduce more "concept clutter"?

I'm not asking for input based on your experience with my specific case, but rather with similar situations you may have faced. Also, both a recommendation and unexpected considerations would be useful.

Note: The wrapper code does not wrap all of the underlying API, so that you only ever go through my code. So it is quite possible users will encounter the mis-named terms in other contexts. On the other hand... uses of my wrappers are always through a namespace i.e. quux::foo or quux::bar.

Answer 1

Funny story: years ago I worked at a company that produced a variety of related data products. A lot of the products were closely related, e.g. could be essentially the same product but in a different format.

At one point when I was responsible for generating a product I had to start attending large monthly status meetings where the product manager got updates on the different related products.

Initially I was feeling rather dumb because I only knew my particular area, and the discussions were sprinkled with lots of acronyms and product abbreviations. To make things worse, sometimes the same name was used for different things, sometimes different names were used for the same thing, depending on who was speaking.

But I gradually picked it up, and after a couple of months I was in one of these meetings where the product owner and a dev were having some back and forth, and I suddenly realized that they were talking about different products! They thought they were talking about the same thing, but they weren't! The products were closely related enough that the conversation wasn't complete nonsense, but the terminology was so confusing that no one else was picking up on it!

Another way to think about this: imagine you are someone using your wrapper. And probably looking at some of the API documentation. I know if it was me, and I noticed that the documentation had the definitions for two items reversed, I wouldn't assume that that was deliberate, I'd assume it was a mistake in the documentation, and I'd probably waste time trying to figure out what's going on.

Bottom line: do not, DO NOT reverse the terminology. You will guarantee confusion down the line. If other developers agree that new terminology is required, come up with some completely new names, and document the relationship to the API names.

Answer 2

Try to see if you can talk to the onces that needs to use your service and do whatever they want. Don't force change anything yourself.

I sort of have the same concept with the dimensions of a book (height/width/depth) The warehouse assumes the book is lying down and the sales people assume the book is standing in a bookshelf.

Answer 3

I have somehow come across this problem, what feels like a ridiculous number of times.

My approach, is mapping the various logics to where the names are still correct, but make it clear that weird things are happing:

Assuming the external API I use has:

class FooBar 
{
  string foo;
  string bar;
}

and I need to call them from the public layer, I might define them in a way that says this is a business representation

string businessFoo;
string businessBar;

And then use a mechanism to map them (AutoMapper for example):

var objectToSave = Map(businessFooBar, fooBar); // return FooBar and sets Bar from businessFoo,
// and Foo from businessBar
callingApi.Save(objectToSave);

I feel this keeps my areas of concern separate, the business layer can deal with business language and keeps terms sane and distinct.

It also means for Unit testing I can check that the maps are not backwards:

var result = Map(businessFoobar, FooBar);
Assert.Equal(businessFoobar.Foo, FooBar.Bar);

It might not be perfect, but it avoids further muddling terms.

Answer 4

Definitely switch the terms so that they make sense. If you're already building a Façade, you might as well make it an Anti-Corruption Layer, too.