Here’s a puzzle. Does a “wrapped URL” refer to the wrapped result, or the original URL input that was wrapped?

Language is our tool, but occasionally we can get confused or go in circles over semantics. Find the story of this brain-bender, and how we clarified it, here.

This all started with a need to fix a particular Tomcat/ OSGi interaction. OSGi URL objects with a special OSGi handler were being wrapped by Tomcat, but the hashCode() behavior wasn’t being delegated to the original handler.

The Tomcat team were very responsive & proposed a patch within a day, but the proposed delegation change wasn’t correct.

I had already observed, on first examination, that the existing code seemed a bit confusing — and terminology seemed part of that. Variables ‘associatedURL’ and ‘resourceURL’ were used, with comments and Javadoc talking vaguely about “the wrapped resource URL”. While ‘associatedURL’ was the wrapped version, it seemed easy to mistake these and this what the initial attempt got wrong.

I proposed a patch to correct the logic and clarify the terminology — renaming ‘associatedURL’ to ‘wrappedURL’.

What does ‘Wrapped URL’ refer to?

An interesting discussion followed, as to whether ‘Wrapped URL’ was clear terminology — or was it actually ambiguous?

I’m not sure wrappedURL is the best terminology either since it is the original resource URL that is wrapped. I think maybe one of wrapperURL, wrappingURL, outerURL or something along those lines would be even better.

While I agree that people could certainly get confused, I felt that somehow this objection wasn’t logically sound.

Looking to explain & clarify this, I finally found some distinctions I could clearly call out:

• The claim that “wrappedURL” is ambiguous isn’t logically correct; it confuses the subject (input) with the verb or transformation being made.
• The fact that you applied an operation (wrapping) to an input to produce a result, does not mean that you can unambiguously describe or identify the input by that operation (“wrapping”).

Using a verb to select is a linguistic shortcut for implicit selectivity, but here the concept was misused; and mistakenly being used to imply that the language was ambiguous.

Implicit selectivity is actually only a shortcut:

• Such a shortcut can be used where there is no ambiguity about which are input & output, but where there is a need to select which of many inputs is applicable; eg. “get Dan’s meal from the fridge”.
• Here however, there is only one input (“one meal”), and the ambiguity is between input and output (“serve the cooked meal”). The question of selectivity — which URL is the handler being called with — applies only in the domain of outputs.

The ‘wrappedURL’ is wrapped with the new URLStreamHandler. The underlying ‘resourceURL’ is not itself wrapped. It is prima facie confusing to refer the resourceURL as itself being wrapped, since it itself is not.

Obviously Dan’s meal will need to be cooked, but we do not refer to the raw meal in the fridge as the “cooked meal” when it is yet to be cooked.

Descriptive Terminology versus Implicit Selection

I felt this was an interesting case, which drew out the distinction between what I’ll call ‘descriptive terminology’ and ‘implicit selection’.

• Descriptive terminology = naming by distinctive important facts
• Implicit selection = selecting by identifying relevant facts of an adjacent object

We can see this in the question about ‘wrappedURL’. The ‘wrappedURL’ is wrapped, while the underlying ‘resourceURL’ is not.

‘Implicit selection’ is to say that “wrapped” might implicitly reference the resourceURL input of the wrapping, rather than the wrappedURL result. But this is purely confused.

Implicit selection can be useful when there are many potential inputs or outputs, and there’s no ambiguity as to which side (input or output) is being spoken about. Then it is reasonable to loosely reference an input of concern by which output it is associated with.

However, descriptive terminology should always take precedence.

In our kitchen analogy, we might ask for “Dan’s meal” or “Sarah’s meal” when there are multiple people. But it must be clear from context whether we are expecting raw or cooked.

Descriptive terminology is naming by actual positive facts. In this case ‘wrapped’ is an actual fact and applies to the output, not the input.

It is mistaken to consider the loose terminology of implicit selection on the same level as accurate descriptive identification, or to avoid the latter because of a meaningless use of implicit selection.

In closing, I offered the following as clear phrasing:

We wrap the underlying Resource URL with a Cache-aware URL Handler, to produce the Wrapped URL.

This clearly distinguishes the input (the Resource URL), the operation (wrapping) and the result (the Wrapped URL).

Conclusion

Language can sometimes be tricky. Yet exactly what’s tricky or confusing can often be hard to pin down.

I think this example was interesting in that it surfaced and seems to clearly characterize, one of the more common problem areas in naming things.

It’s worth clearly distinguishing between descriptive terminology, which should be preferred, and implicit selection. Implicit selection is a secondary shorthand which is sometimes useful but can, as in this case, also become a source of significant confusion.

Have you encountered confusion with naming? Share your thoughts!