Arose buy any other name wood smell as suite.
Programming is sometimes like writing poetry (although with perhaps slightly less social stigma): the choice of words is of utmost importance. Using the right word in the right place can make your code immediately comprehensible, even elegant. Conversely, choosing the wrong word can make code unbelievably complex. You have to be especially careful of words with more than one meaning, even more so when those meanings are similar but subtly different.
When writing the dynamic mock library I used the word "call" to refer to an incoming method call that was to be checked and given a mock behaviour by a mock object. A dynamic mock object intercepted each method call, created a Call object to represent the call, and passed it to a Callable object that checked expectations and stubbed their behaviour. A Callable had a method called "call" that took one argument, a Call called "call". Err... got that? Or are you getting as confused as I did? Perhaps some code will help...
interface Callable {
public Object call( Call call ) throws Throwable;
}
Here's how it is called:
Call call = new Call( ... ); Callable callable = findMatchingCallable(call); return callable.call( call );
That naming scheme is incredibly confusing. The word "call" is being used as a noun and a verb, to refer to a class, a variable holding a reference to an instance of that class, and to a method. And that's ignoring that "called" also means "named"!
As part of the refactoring of the jMock codebase we renamed Call to Invocation and the call method to invoke:
interface Invokable {
public Object invoke( Invocation invocation ) throws Throwable;
}
Now the framework uses distinct nouns and verbs, and code is much easier to read. More importantly, members of a pair can talk about the code while programming without getting each other completely confused.